@imdeadpool/guardex 6.1.0 → 7.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "6.1.0",
+  "version": "7.0.1",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -10,8 +10,6 @@
     "multiagent-safety": "bin/multiagent-safety.js"
   },
   "scripts": {
-    "prepack": "node pack-helpers/dereference-templates.mjs",
-    "postpack": "git checkout -- templates",
     "test": "node --test test/*.test.js",
     "agent:codex": "bash ./scripts/codex-agent.sh",
     "agent:branch:start": "bash ./scripts/agent-branch-start.sh",
@@ -27,8 +25,8 @@
     "agent:branch:sync": "gx sync",
     "agent:branch:sync:check": "gx sync --check",
     "agent:safety:setup": "gx setup",
-    "agent:safety:scan": "gx scan",
-    "agent:safety:fix": "gx fix",
+    "agent:safety:scan": "gx status --strict",
+    "agent:safety:fix": "gx setup --repair",
     "agent:safety:doctor": "gx doctor",
     "agent:review:watch": "bash ./scripts/review-bot-watch.sh",
     "agent:finish": "gx finish --all"

package/templates/AGENTS.multiagent-safety.md

@@ -1,92 +1,19 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Execution Contract (GX)
+## Multi-Agent Safety Contract
 
-0. Session plan comment + read gate (required)
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions — bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
 
-- Before editing, each agent must post a short session comment/handoff note that includes:
-  - plan/change name (or checkpoint id),
-  - owned files/scope,
-  - intended action.
-- Before deleting/replacing code, each agent must read the latest session comments/handoffs first and confirm the target code is in their owned scope.
-- If ownership is unclear or overlaps, stop that edit, post a blocker comment, and let the leader/integrator reassign scope.
-- For git isolation, each agent must start on a dedicated branch via `scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"`.
-- In-place branch mode is disallowed: never switch the active local/base checkout to an agent branch.
-- Primary-checkout immutability: agents MUST NOT run `git checkout <branch>` on any repo's primary working tree, including nested repos inside the parent workspace (e.g. tool repos nested under the product repo). Keep each repo's primary checkout on its base/protected branch; use `git worktree add` for feature work. The `.githooks/post-checkout` hook auto-reverts primary-checkout branch switches when an agent session is detected; bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1` when truly intentional.
-- Treat the base branch (`main` or the user's current local base branch) as read-only while the agent branch is active.
-- Agent completion defaults to `scripts/codex-agent.sh`, which auto-finishes the branch (auto-commit changed files, push/create PR, attempt merge, and pull the local base branch after merge).
-- OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR for those changes (via `codex-agent` or `agent-branch-finish`).
-- Auto-finish now waits for required checks/merge and then cleans merged sandbox branch/worktree by default.
-- Use `--no-cleanup` only when you explicitly need to keep a merged sandbox for audit/debug follow-up.
-- If codex-agent auto-finish cannot complete, immediately run `scripts/agent-branch-finish.sh --branch "<agent-branch>" --base dev --via-pr --wait-for-merge` and keep the branch open until checks/review pass.
-- If merge/rebase conflicts block auto-finish, run a conflict-resolution review pass in that sandbox branch, then rerun `agent-branch-finish.sh --base dev --via-pr --wait-for-merge` until merged.
-- Completion is not valid until these are true: commit exists on the agent branch, branch is pushed to `origin`, and PR/merge status is produced by `agent-branch-finish.sh` or `codex-agent`.
-- For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch; otherwise create a fresh one from the current local base snapshot with `scripts/agent-branch-start.sh`.
-- Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
-- If the change publishes or bumps a version, the same change must also update release notes/changelog entries.
+**Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
-1. Explicit ownership before edits
+**Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
 
-- Assign each agent clear file/module ownership.
-- Do not edit files outside your assigned scope unless the leader reassigns ownership.
+**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop — don't half-finish.
 
-2. Preserve parallel safety
+**Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
-- Assume other agents are editing nearby code concurrently.
-- Never revert unrelated changes authored by others.
-- If another change conflicts with your approach, adapt and report the conflict in handoff.
+**Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
-3. Verify before completion
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
-- Run required local checks for the area you changed.
-- Do not mark work complete without command output evidence.
-
-4. Required handoff format (every agent)
-
-- Files changed
-- Behavior touched
-- Verification commands + results
-- Risks / follow-ups
-
-## OpenSpec Workspaces (required for agent sub-branch changes)
-
-OMX Codex execution flows must use OpenSpec. `scripts/codex-agent.sh` bootstraps
-per-branch OpenSpec workspaces automatically:
-
-```text
-openspec/changes/<agent-branch-slug>/
-openspec/plan/<agent-branch-slug>/
-```
-
-For manual `scripts/agent-branch-start.sh` usage, enable auto-bootstrap with
-`GUARDEX_OPENSPEC_AUTO_INIT=true` or scaffold manually before implementation:
-
-```bash
-bash scripts/openspec/init-change-workspace.sh "<change-slug>" "<capability-slug>"
-bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
-```
-
-Expected change shape:
-
-```text
-openspec/changes/<change-slug>/
-  .openspec.yaml
-  proposal.md
-  tasks.md
-  specs/<capability-slug>/spec.md
-```
-
-Expected plan shape:
-
-```text
-openspec/plan/<plan-slug>/
-  summary.md
-  checkpoints.md
-  planner/plan.md
-  planner/tasks.md
-  architect/tasks.md
-  critic/tasks.md
-  executor/tasks.md
-  writer/tasks.md
-  verifier/tasks.md
-```
+**Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/claude/commands/guardex.md

@@ -1,18 +1,12 @@
 # /guardex
 
-Run a GuardeX check-and-repair workflow for the current repository.
+Run a GuardeX check-and-repair for the current repo.
 
 ## Steps
 
-1. Run `gx status`.
-2. If status is degraded, run `gx doctor`.
-3. If still degraded, run `gx scan` and summarize each finding with a fix.
-4. Report final verdict as one of:
-   - `Repo is guarded`
-   - `Repo is not guarded` (include blockers)
+1. `gx status` — if green, stop.
+2. If degraded, `gx doctor`.
+3. If still degraded, `gx status --strict` and summarize each finding with a fix.
+4. Report verdict: `Repo is guarded` or `Repo is not guarded` (list blockers).
 
-## Style
-
-- Keep output short and operational.
-- Include exact commands you executed.
-- Prefer concrete next actions over generic advice.
+Keep output short, include the exact commands you ran.

package/templates/codex/skills/guardex/SKILL.md

@@ -1,89 +1,43 @@
 ---
 name: guardex
-description: "Use when you need to check, repair, or bootstrap multi-agent safety guardrails in this repository."
+description: "Check, repair, or bootstrap multi-agent safety guardrails in this repository."
 ---
 
 # GuardeX (Codex skill)
 
-Use this skill whenever branch safety, lock ownership, or guardrail setup may be broken.
+Use when branch safety, lock ownership, or guardrail setup may be broken.
 
 ## Fast path
 
-1. Run `gx status`.
-2. If repo safety is degraded, run `gx doctor`.
-3. If issues remain, run `gx scan` and address the findings.
+1. `gx status` — one-glance health check.
+2. If degraded, `gx doctor` — repair + verify in one pass.
+3. If issues remain, `gx status --strict` and address each finding.
 
-## Setup path
-
-If guardrails are missing entirely, run:
-
-```sh
-gx setup
-# alias
-gx init
-```
-
-Then verify:
+## Bootstrap (missing guardrails)
 
 ```sh
-gx status
-gx scan
+gx setup      # install + repair + verify
+gx status     # confirm green
 ```
 
-## Operator notes
-
-- Prefer `gx doctor` for one-step repair + verification.
-- Keep agent work isolated (`agent/*` branches + lock claims).
-- For every new user message/task, restart the full loop on a fresh agent branch/worktree.
-- For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
-- `scripts/codex-agent.sh` auto-syncs the sandbox branch against base before each task and auto-finishes merge/PR flow after Codex exits.
-- Auto-finish keeps the branch/worktree by default; remove merged branches explicitly with `gx cleanup` (or `gx cleanup --branch "<agent-branch>"`).
-- For skill-file-only merges into the local base branch (`dev` by default), use `$guardex-merge-skills-to-dev`.
-- Do not bypass protected branch safeguards unless explicitly required.
+In a monorepo with nested git repos (top-level `.git` plus `apps/*/.git`), `gx setup` auto-installs into every discovered repo. Submodules and guardex-managed worktrees are skipped. Pass `--no-recursive` to limit to the top-level only.
 
-## Bulk merge runbook (changed agent branches)
+## Notes
 
-Use this when a repo has many `agent/*` branches/worktrees with pending changes and you need them merged into the base branch quickly.
+- Isolation: `scripts/codex-agent.sh "<task>" "<agent>"` is the one-command sandbox start/finish loop.
+- Completion: auto-finish keeps the branch until explicit `gx cleanup`.
+- Never bypass protected-branch safeguards.
 
-1. Confirm base and guardrails are healthy:
+## Bulk finish
 
 ```sh
-git status --short --branch
-git pull --ff-only origin "$(git config --get multiagent.baseBranch || echo dev)"
-gx scan
+gx finish --all                # commit + PR + merge all ready agent/* branches
+gx cleanup                     # prune merged/stale branches and worktrees
 ```
 
-2. Run bulk finish first:
-
-```sh
-gx finish --all
-```
-
-3. If a branch fails with `already used by worktree` or stale rebase hints, clear the stale state in that worktree, then retry targeted finish:
+If a branch fails with stale rebase/worktree state:
 
 ```sh
 git -C "<worktree>" rebase --abort || true
-gx finish --branch "<agent-branch>" --base "$(git config --get multiagent.baseBranch || echo dev)" --no-wait-for-merge --cleanup
-```
-
-4. If `gh pr merge` exits non-zero due local branch deletion but PR is already merged, treat it as merged and verify with:
-
-```sh
-gh pr view "<pr-number>" --json state,mergedAt,url
-```
-
-5. If a branch is still ahead of base with no open PR, create and merge a follow-up PR manually:
-
-```sh
-gh pr create --base "<base-branch>" --head "<agent-branch>" --title "Auto-finish: <agent-branch>" --body "Follow-up merge for pending branch commits."
-gh pr merge "<pr-number>" --squash --delete-branch
-```
-
-6. Final verification:
-
-```sh
-gh pr list --state open --search "head:agent/ base:<base-branch>"
-git pull --ff-only origin "<base-branch>"
-gx cleanup
-gx scan
+gx finish --branch "<agent-branch>" --cleanup
 ```

package/templates/githooks/post-merge

@@ -1,7 +1,43 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# Auto-sync agent worktrees when the base branch is updated in this worktree.
-if [[ -x "scripts/agent-sync-on-base-update.sh" ]]; then
-  bash scripts/agent-sync-on-base-update.sh --quiet || true
+if [[ "${GUARDEX_DISABLE_POST_MERGE_CLEANUP:-0}" == "1" ]]; then
+  exit 0
 fi
+
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$repo_root" ]]; then
+  exit 0
+fi
+
+branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ -z "$branch" || "$branch" == "HEAD" ]]; then
+  exit 0
+fi
+
+base_branch="${GUARDEX_BASE_BRANCH:-$(git -C "$repo_root" config --get multiagent.baseBranch || true)}"
+if [[ -z "$base_branch" ]]; then
+  base_branch="dev"
+fi
+
+if [[ "$branch" != "$base_branch" ]]; then
+  exit 0
+fi
+
+cli_path="$repo_root/bin/multiagent-safety.js"
+if [[ ! -f "$cli_path" ]]; then
+  exit 0
+fi
+
+node_bin="${GUARDEX_NODE_BIN:-node}"
+if ! command -v "$node_bin" >/dev/null 2>&1; then
+  exit 0
+fi
+
+"$node_bin" "$cli_path" cleanup \
+  --target "$repo_root" \
+  --base "$base_branch" \
+  --include-pr-merged \
+  --keep-clean-worktrees >/dev/null 2>&1 || true
+
+exit 0

package/templates/githooks/pre-commit

@@ -9,12 +9,6 @@ if [[ -z "$branch" ]]; then
   exit 0
 fi
 
-git_dir="$(git rev-parse --git-dir 2>/dev/null || true)"
-is_linked_worktree=0
-if [[ -n "$git_dir" && "$git_dir" == *"/worktrees/"* ]]; then
-  is_linked_worktree=1
-fi
-
 if [[ "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
   exit 0
 fi
@@ -30,7 +24,7 @@ if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}"
 fi
 
 is_vscode_git_context=0
-if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" || "${TERM_PROGRAM:-}" == "vscode" ]]; then
+if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" ]]; then
   is_vscode_git_context=1
 fi
 
@@ -74,163 +68,6 @@ case "$codex_require_agent_branch" in
   *) should_require_codex_agent_branch=1 ;;
 esac
 
-sanitize_slug() {
-  local raw="$1"
-  local fallback="${2:-task}"
-  local slug
-  slug="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
-  if [[ -z "$slug" ]]; then
-    slug="$fallback"
-  fi
-  printf '%s' "$slug"
-}
-
-resolve_agent_branch_base() {
-  local branch_name="$1"
-  git config --get "branch.${branch_name}.guardexBase" || true
-}
-
-is_helper_agent_branch() {
-  local branch_name="$1"
-  local base_branch=""
-  base_branch="$(resolve_agent_branch_base "$branch_name")"
-  [[ "$base_branch" == agent/* ]]
-}
-
-ensure_agent_branch_openspec_workspace() {
-  local branch_name="$1"
-  local change_slug change_dir specs_dir capability_slug branch_base
-  local missing_workspace=0
-  local openspec_script="scripts/openspec/init-change-workspace.sh"
-
-  branch_base="$(git config --get "branch.${branch_name}.guardexBase" || true)"
-  if [[ "$branch_base" == agent/* ]]; then
-    echo "[agent-openspec-guard] Skipping OpenSpec change workspace bootstrap for helper branch '${branch_name}' (base '${branch_base}')."
-    return 0
-  fi
-
-  change_slug="$(sanitize_slug "${branch_name//\//-}" "change")"
-  change_dir="openspec/changes/${change_slug}"
-  specs_dir="${change_dir}/specs"
-
-  if [[ ! -f "${change_dir}/.openspec.yaml" || ! -f "${change_dir}/proposal.md" || ! -f "${change_dir}/tasks.md" ]]; then
-    missing_workspace=1
-  elif [[ ! -d "$specs_dir" ]] || ! find "$specs_dir" -mindepth 2 -maxdepth 2 -type f -name spec.md | grep -q .; then
-    missing_workspace=1
-  fi
-
-  if [[ "$missing_workspace" -ne 1 ]]; then
-    return 0
-  fi
-
-  if [[ ! -f "$openspec_script" ]]; then
-    cat >&2 <<MSG
-[agent-openspec-guard] Missing OpenSpec change workspace for '${branch_name}'.
-Expected path:
-  ${change_dir}
-Cannot auto-initialize because '${openspec_script}' is missing.
-Run:
-  gx setup --target "$(git rev-parse --show-toplevel)"
-  bash scripts/openspec/init-change-workspace.sh "${change_slug}" "<capability-slug>"
-MSG
-    exit 1
-  fi
-
-  if [[ ! -x "$openspec_script" ]]; then
-    chmod +x "$openspec_script" 2>/dev/null || true
-  fi
-
-  capability_slug="$(sanitize_slug "${branch_name##*/}" "general-behavior")"
-  init_output=""
-  if ! init_output="$(bash "$openspec_script" "$change_slug" "$capability_slug" 2>&1)"; then
-    printf '%s\n' "$init_output" >&2
-    cat >&2 <<MSG
-[agent-openspec-guard] OpenSpec auto-init failed for '${branch_name}'.
-Run manually:
-  bash scripts/openspec/init-change-workspace.sh "${change_slug}" "${capability_slug}"
-MSG
-    exit 1
-  fi
-
-  if [[ -n "$init_output" ]]; then
-    printf '%s\n' "$init_output"
-  fi
-
-  git add "$change_dir"
-
-  if [[ -x scripts/agent-file-locks.py ]]; then
-    staged_openspec="$(git diff --cached --name-only -- "$change_dir" | sed '/^$/d' || true)"
-    if [[ -n "$staged_openspec" ]]; then
-      mapfile -t openspec_files < <(printf '%s\n' "$staged_openspec")
-      python3 scripts/agent-file-locks.py claim --branch "$branch_name" "${openspec_files[@]}" >/dev/null 2>&1 || true
-    fi
-  fi
-
-  echo "[agent-openspec-guard] Bootstrapped OpenSpec change workspace: ${change_dir}"
-}
-
-should_auto_reroute_protected_branch() {
-  local raw="${GUARDEX_AUTO_REROUTE_PROTECTED_BRANCH:-$(git config --get multiagent.autoRerouteProtectedBranch || true)}"
-  local lowered=""
-  if [[ -z "$raw" ]]; then
-    raw="true"
-  fi
-  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
-  case "$lowered" in
-    1|true|yes|on) return 0 ;;
-    *) return 1 ;;
-  esac
-}
-
-auto_reroute_protected_branch_commit() {
-  local branch_name="$1"
-  local starter_script="scripts/agent-branch-start.sh"
-  local task_name="${GUARDEX_AUTO_REROUTE_TASK_NAME:-protected-branch-commit-reroute}"
-  local agent_name="${GUARDEX_AUTO_REROUTE_AGENT_NAME:-auto-reroute}"
-  local changed_paths=""
-  local start_output=""
-  local start_status=0
-  local new_branch=""
-  local worktree_path=""
-
-  changed_paths="$({
-    git diff --name-only
-    git diff --cached --name-only
-    git ls-files --others --exclude-standard
-  } | sed '/^$/d' | sort -u)"
-
-  if [[ -z "$changed_paths" ]]; then
-    return 1
-  fi
-
-  if [[ ! -x "$starter_script" ]]; then
-    return 1
-  fi
-
-  set +e
-  start_output="$(bash "$starter_script" "$task_name" "$agent_name" "$branch_name" 2>&1)"
-  start_status=$?
-  set -e
-
-  if [[ "$start_status" -ne 0 ]]; then
-    printf '%s\n' "$start_output" >&2
-    return 1
-  fi
-
-  new_branch="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Created branch: //p' | tail -n 1)"
-  worktree_path="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | tail -n 1)"
-
-  printf '%s\n' "$start_output" >&2
-  cat >&2 <<MSG
-[agent-branch-guard] Protected-branch commit rerouted automatically.
-Changes from '${branch_name}' were moved to:
-  branch: ${new_branch:-<see output>}
-  worktree: ${worktree_path:-<see output>}
-Continue work and commit from that agent worktree.
-MSG
-  return 0
-}
-
 is_codex_managed_only_commit_on_protected=0
 if [[ "$is_codex_session" == "1" && "$is_protected_branch" == "1" ]]; then
   deleted_paths="$(git diff --cached --name-only --diff-filter=D)"
@@ -286,30 +123,15 @@ MSG
   fi
 fi
 
-if [[ "$is_codex_session" == "1" && "$branch" == agent/* ]]; then
-  if [[ "$is_linked_worktree" != "1" && "${GUARDEX_ALLOW_CODEX_ON_PRIMARY_WORKTREE:-0}" != "1" ]]; then
-    cat >&2 <<'MSG'
-[codex-worktree-guard] Codex agent commits are blocked from the primary checkout.
-Use a linked agent worktree for agent/* branches:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
-Then commit from the printed worktree path.
-
-Temporary bypass (not recommended):
-  GUARDEX_ALLOW_CODEX_ON_PRIMARY_WORKTREE=1 git commit ...
-MSG
-    exit 1
-  fi
-fi
-
 if [[ "$is_protected_branch" == "1" ]]; then
-  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" && "$allow_vscode_protected_branch_writes" == "1" ]]; then
-    exit 0
+  if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
+    if [[ "$allow_vscode_protected_branch_writes" == "1" ]]; then
+      exit 0
+    fi
   fi
 
-  if should_auto_reroute_protected_branch; then
-    if auto_reroute_protected_branch_commit "$branch"; then
-      exit 1
-    fi
+  if [[ "$is_unborn_branch" == "1" && "$is_codex_session" != "1" ]]; then
+    exit 0
   fi
 
   git_dir="$(git rev-parse --git-dir)"
@@ -323,10 +145,8 @@ Use an agent branch first:
   bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
 After finishing work:
   bash scripts/agent-branch-finish.sh
-Auto-reroute can be disabled (not recommended):
-  GUARDEX_AUTO_REROUTE_PROTECTED_BRANCH=0 git commit ...
 
-Optional repo override for manual VS Code protected-branch commits:
+Optional repo opt-in for VS Code protected-branch commits:
   git config multiagent.allowVscodeProtectedBranchWrites true
 
 Temporary bypass (not recommended):
@@ -335,12 +155,26 @@ MSG
   exit 1
 fi
 
+if [[ "$is_agent_context" == "1" && "$branch" != agent/* ]]; then
+  cat >&2 <<'MSG'
+[agent-branch-guard] Agent commits must run on dedicated agent/* branches.
+Start an agent branch first:
+  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+Then commit on that branch.
+
+Temporary bypass (not recommended):
+  ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
+MSG
+  exit 1
+fi
+
 if [[ "$branch" == agent/* ]]; then
-  if is_helper_agent_branch "$branch"; then
-    helper_base="$(resolve_agent_branch_base "$branch")"
-    echo "[agent-openspec-guard] Skipping OpenSpec change workspace bootstrap for helper branch '${branch}' (base '${helper_base}')."
-  else
-    ensure_agent_branch_openspec_workspace "$branch"
+  if [[ "${GUARDEX_AUTOCLAIM_STAGED_LOCKS:-1}" == "1" ]]; then
+    while IFS= read -r staged_file; do
+      [[ -z "$staged_file" ]] && continue
+      [[ "$staged_file" == ".omx/state/agent-file-locks.json" ]] && continue
+      python3 scripts/agent-file-locks.py claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
+    done < <(git diff --cached --name-only --diff-filter=ACMRDTUXB)
   fi
 
   if ! python3 scripts/agent-file-locks.py validate --branch "$branch" --staged; then