@imdeadpool/guardex 7.0.15 → 7.0.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.15",
-  "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
+  "version": "7.0.18",
+  "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,
   "bin": {
@@ -15,6 +15,7 @@
     "agent:codex": "bash ./scripts/codex-agent.sh",
     "agent:branch:start": "bash ./scripts/agent-branch-start.sh",
     "agent:branch:finish": "bash ./scripts/agent-branch-finish.sh",
+    "agent:branch:merge": "bash ./scripts/agent-branch-merge.sh",
     "agent:cleanup": "gx cleanup",
     "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
     "agent:locks:claim": "python3 ./scripts/agent-file-locks.py claim",

package/templates/AGENTS.multiagent-safety.md

@@ -7,22 +7,22 @@
 `GUARDEX_ON=0` disables Guardex for that repo.
 `GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
-**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`.
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<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`.
 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 instead of creating a fresh lane unless the user explicitly redirects scope.
 Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**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.
+**Ownership.** Before editing, claim files: `gx locks claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
 **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.
 
-**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.
+**Completion.** Finish with `gx branch finish --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.
 OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
 **Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
 **Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
 
-**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `scripts/agent-branch-finish.sh ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/githooks/post-checkout

@@ -64,7 +64,7 @@ echo "[agent-primary-branch-guard] Primary checkout switched branches." >&2
 echo "[agent-primary-branch-guard]   from: $prev_branch (protected)" >&2
 echo "[agent-primary-branch-guard]   to:   $new_branch" >&2
 echo "[agent-primary-branch-guard] The primary working tree must stay on its base/protected branch." >&2
-echo "[agent-primary-branch-guard] Use 'git worktree add' (or scripts/agent-branch-start.sh) for feature work." >&2
+echo "[agent-primary-branch-guard] Use 'git worktree add' (or gx branch start) for feature work." >&2
 
 if [[ "$is_agent" == "1" ]]; then
   echo "[agent-primary-branch-guard] Agent session detected — reverting to '$prev_branch'." >&2

package/templates/githooks/post-merge

@@ -32,17 +32,30 @@ if [[ "$branch" != "$base_branch" ]]; then
   exit 0
 fi
 
-cli_path="$repo_root/bin/multiagent-safety.js"
-if [[ ! -f "$cli_path" ]]; then
+if [[ -n "${GUARDEX_CLI_ENTRY:-}" ]]; then
+  node_bin="${GUARDEX_NODE_BIN:-node}"
+  if command -v "$node_bin" >/dev/null 2>&1; then
+    "$node_bin" "$GUARDEX_CLI_ENTRY" cleanup \
+      --target "$repo_root" \
+      --base "$base_branch" \
+      --include-pr-merged \
+      --keep-clean-worktrees >/dev/null 2>&1 || true
+  fi
   exit 0
 fi
 
-node_bin="${GUARDEX_NODE_BIN:-node}"
-if ! command -v "$node_bin" >/dev/null 2>&1; then
-  exit 0
+cli_bin="${GUARDEX_CLI_BIN:-}"
+if [[ -z "$cli_bin" ]]; then
+  if command -v gx >/dev/null 2>&1; then
+    cli_bin="gx"
+  elif command -v gitguardex >/dev/null 2>&1; then
+    cli_bin="gitguardex"
+  else
+    exit 0
+  fi
 fi
 
-"$node_bin" "$cli_path" cleanup \
+"$cli_bin" cleanup \
   --target "$repo_root" \
   --base "$base_branch" \
   --include-pr-merged \

package/templates/githooks/pre-commit

@@ -116,11 +116,11 @@ if [[ "$should_require_codex_agent_branch" == "1" && "${GUARDEX_ALLOW_CODEX_ON_N
 
       cat >&2 <<'MSG'
 [guardex-preedit-guard] Codex edit/commit detected on a protected branch.
-GuardeX requires Codex work to run from an isolated agent/* branch.
+GitGuardex requires Codex work to run from an isolated agent/* branch.
 Start the sub-branch/worktree with:
-  bash scripts/codex-agent.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Or manually:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -132,7 +132,7 @@ MSG
     cat >&2 <<'MSG'
 [codex-branch-guard] Codex agent commit blocked on non-agent branch.
 Use isolated branch/worktree first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -163,9 +163,9 @@ if [[ "$is_protected_branch" == "1" ]]; then
   cat >&2 <<'MSG'
 [agent-branch-guard] Direct commits on protected branches are blocked.
 Use an agent branch first:
-  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 After finishing work:
-  bash scripts/agent-branch-finish.sh
+  gx branch finish
 
 Temporary bypass (not recommended):
   ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
@@ -177,7 +177,7 @@ if [[ "$is_agent_session" == "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>"
+  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit on that branch.
 
 Temporary bypass (not recommended):
@@ -199,7 +199,7 @@ if [[ "$branch" == agent/* ]]; then
     cat >&2 <<'MSG'
 [agent-branch-guard] Agent branch commits require file ownership locks.
 Claim files first:
-  python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
+  gx locks claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
 MSG
     exit 1
   fi

package/templates/scripts/agent-branch-merge.sh

@@ -0,0 +1,421 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_BRANCH=""
+BASE_BRANCH_EXPLICIT=0
+TARGET_BRANCH=""
+TASK_NAME=""
+AGENT_NAME="${GUARDEX_MERGE_AGENT_NAME:-codex}"
+declare -a SOURCE_BRANCHES=()
+
+usage() {
+  cat <<'EOF'
+Usage: scripts/agent-branch-merge.sh --branch <agent/...> [--branch <agent/...> ...] [--into <agent/...>] [--task <task>] [--agent <agent>] [--base <branch>]
+
+Examples:
+  bash scripts/agent-branch-merge.sh --branch agent/codex/ui-a --branch agent/codex/ui-b
+  bash scripts/agent-branch-merge.sh --into agent/codex/owner-lane --branch agent/codex/helper-a --branch agent/codex/helper-b
+EOF
+}
+
+sanitize_slug() {
+  local raw="$1"
+  local fallback="${2:-merge-agent-branches}"
+  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_base_branch() {
+  local repo="$1"
+  local explicit_target="$2"
+  local configured=""
+  local branch_base=""
+
+  if [[ -n "$explicit_target" ]]; then
+    branch_base="$(git -C "$repo" config --get "branch.${explicit_target}.guardexBase" || true)"
+    if [[ -n "$branch_base" ]]; then
+      printf '%s' "$branch_base"
+      return 0
+    fi
+  fi
+
+  configured="$(git -C "$repo" config --get multiagent.baseBranch || true)"
+  if [[ -n "$configured" ]]; then
+    printf '%s' "$configured"
+    return 0
+  fi
+
+  for fallback in dev main master; do
+    if git -C "$repo" show-ref --verify --quiet "refs/heads/${fallback}" \
+      || git -C "$repo" show-ref --verify --quiet "refs/remotes/origin/${fallback}"; then
+      printf '%s' "$fallback"
+      return 0
+    fi
+  done
+
+  printf '%s' "dev"
+}
+
+get_worktree_for_branch() {
+  local repo="$1"
+  local branch="$2"
+  git -C "$repo" worktree list --porcelain | awk -v target="refs/heads/${branch}" '
+    $1 == "worktree" { wt = $2 }
+    $1 == "branch" && $2 == target { print wt; exit }
+  '
+}
+
+is_clean_worktree() {
+  local wt="$1"
+  git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
+    && git -C "$wt" diff --cached --quiet -- . ":(exclude).omx/state/agent-file-locks.json" \
+    && [[ -z "$(git -C "$wt" ls-files --others --exclude-standard)" ]]
+}
+
+has_in_progress_git_op() {
+  local wt="$1"
+  local git_dir=""
+  git_dir="$(git -C "$wt" rev-parse --git-dir 2>/dev/null || true)"
+  if [[ -z "$git_dir" ]]; then
+    return 1
+  fi
+  if [[ "$git_dir" != /* ]]; then
+    git_dir="$(cd "$wt/$git_dir" 2>/dev/null && pwd -P || true)"
+  fi
+  if [[ -z "$git_dir" ]]; then
+    return 1
+  fi
+  [[ -f "${git_dir}/MERGE_HEAD" || -d "${git_dir}/rebase-merge" || -d "${git_dir}/rebase-apply" ]]
+}
+
+select_unique_worktree_path() {
+  local root="$1"
+  local name="$2"
+  local candidate="${root}/${name}"
+  local suffix=2
+  while [[ -e "$candidate" ]]; do
+    candidate="${root}/${name}-${suffix}"
+    suffix=$((suffix + 1))
+  done
+  printf '%s' "$candidate"
+}
+
+branch_exists() {
+  local repo="$1"
+  local branch="$2"
+  git -C "$repo" show-ref --verify --quiet "refs/heads/${branch}"
+}
+
+branch_is_agent_lane() {
+  local branch="$1"
+  [[ "$branch" == agent/* ]]
+}
+
+array_contains() {
+  local needle="$1"
+  shift || true
+  local item
+  for item in "$@"; do
+    if [[ "$item" == "$needle" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+collect_branch_files() {
+  local repo="$1"
+  local base_ref="$2"
+  local branch="$3"
+  git -C "$repo" diff --name-only "${base_ref}...${branch}" -- . ":(exclude).omx/state/agent-file-locks.json" 2>/dev/null || true
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      BASE_BRANCH="${2:-}"
+      BASE_BRANCH_EXPLICIT=1
+      shift 2
+      ;;
+    --into)
+      TARGET_BRANCH="${2:-}"
+      shift 2
+      ;;
+    --branch)
+      SOURCE_BRANCHES+=("${2:-}")
+      shift 2
+      ;;
+    --task)
+      TASK_NAME="${2:-}"
+      shift 2
+      ;;
+    --agent)
+      AGENT_NAME="${2:-codex}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "[agent-branch-merge] Unknown argument: $1" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "[agent-branch-merge] Not inside a git repository." >&2
+  exit 1
+fi
+
+repo_root="$(git rev-parse --show-toplevel)"
+common_git_dir_raw="$(git -C "$repo_root" rev-parse --git-common-dir)"
+if [[ "$common_git_dir_raw" == /* ]]; then
+  common_git_dir="$common_git_dir_raw"
+else
+  common_git_dir="$(cd "$repo_root/$common_git_dir_raw" && pwd -P)"
+fi
+repo_common_root="$(cd "$common_git_dir/.." && pwd -P)"
+agent_worktree_root="${repo_common_root}/.omx/agent-worktrees"
+mkdir -p "$agent_worktree_root"
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] --base requires a branch value." >&2
+  exit 1
+fi
+
+if [[ -z "$TARGET_BRANCH" && "${#SOURCE_BRANCHES[@]}" -lt 1 ]]; then
+  echo "[agent-branch-merge] Provide at least one --branch <agent/...> source lane." >&2
+  exit 1
+fi
+
+if [[ -n "$TARGET_BRANCH" ]] && ! branch_is_agent_lane "$TARGET_BRANCH"; then
+  echo "[agent-branch-merge] --into must reference an agent/* branch: ${TARGET_BRANCH}" >&2
+  exit 1
+fi
+
+deduped_sources=()
+for branch in "${SOURCE_BRANCHES[@]}"; do
+  if [[ -z "$branch" ]]; then
+    echo "[agent-branch-merge] --branch requires an agent/* branch value." >&2
+    exit 1
+  fi
+  if ! branch_is_agent_lane "$branch"; then
+    echo "[agent-branch-merge] Source branch must be agent/*: ${branch}" >&2
+    exit 1
+  fi
+  if ! branch_exists "$repo_root" "$branch"; then
+    echo "[agent-branch-merge] Local source branch not found: ${branch}" >&2
+    exit 1
+  fi
+  if ! array_contains "$branch" "${deduped_sources[@]}"; then
+    deduped_sources+=("$branch")
+  fi
+done
+SOURCE_BRANCHES=("${deduped_sources[@]}")
+
+if [[ "${#SOURCE_BRANCHES[@]}" -eq 0 ]]; then
+  echo "[agent-branch-merge] No unique source branches were provided." >&2
+  exit 1
+fi
+
+if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
+  BASE_BRANCH="$(resolve_base_branch "$repo_root" "$TARGET_BRANCH")"
+fi
+
+if [[ -z "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] Unable to resolve a base branch." >&2
+  exit 1
+fi
+
+start_ref="$BASE_BRANCH"
+if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
+  git -C "$repo_root" fetch origin "$BASE_BRANCH" --quiet
+  start_ref="origin/${BASE_BRANCH}"
+elif ! git -C "$repo_root" show-ref --verify --quiet "refs/heads/${BASE_BRANCH}"; then
+  echo "[agent-branch-merge] Base branch not found locally or on origin: ${BASE_BRANCH}" >&2
+  exit 1
+fi
+
+target_worktree=""
+target_created=0
+
+if [[ -z "$TARGET_BRANCH" ]]; then
+  if [[ -z "$TASK_NAME" ]]; then
+    first_hint="$(printf '%s' "${SOURCE_BRANCHES[0]}" | sed -E 's#^agent/[^/]+/##; s#^agent/##')"
+    source_count="${#SOURCE_BRANCHES[@]}"
+    if [[ "$source_count" -gt 1 ]]; then
+      TASK_NAME="$(sanitize_slug "merge-${first_hint}-and-$((source_count - 1))-more" "merge-agent-branches")"
+    else
+      TASK_NAME="$(sanitize_slug "merge-${first_hint}" "merge-agent-branches")"
+    fi
+  else
+    TASK_NAME="$(sanitize_slug "$TASK_NAME" "merge-agent-branches")"
+  fi
+
+  start_output=""
+  if ! start_output="$(
+    cd "$repo_root"
+    env GUARDEX_OPENSPEC_AUTO_INIT=1 bash "scripts/agent-branch-start.sh" "$TASK_NAME" "$AGENT_NAME" "$BASE_BRANCH" 2>&1
+  )"; then
+    printf '%s\n' "$start_output" >&2
+    exit 1
+  fi
+
+  printf '%s\n' "$start_output"
+  TARGET_BRANCH="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Created branch: //p' | head -n 1)"
+  target_worktree="$(printf '%s\n' "$start_output" | sed -n 's/^\[agent-branch-start\] Worktree: //p' | head -n 1)"
+  if [[ -z "$TARGET_BRANCH" || -z "$target_worktree" ]]; then
+    echo "[agent-branch-merge] Unable to parse target branch/worktree from agent-branch-start output." >&2
+    exit 1
+  fi
+  target_created=1
+else
+  if ! branch_exists "$repo_root" "$TARGET_BRANCH"; then
+    echo "[agent-branch-merge] Target branch not found: ${TARGET_BRANCH}" >&2
+    exit 1
+  fi
+
+  target_worktree="$(get_worktree_for_branch "$repo_root" "$TARGET_BRANCH")"
+  if [[ -z "$target_worktree" ]]; then
+    target_worktree="$(select_unique_worktree_path "$agent_worktree_root" "${TARGET_BRANCH//\//__}")"
+    git -C "$repo_root" worktree add "$target_worktree" "$TARGET_BRANCH" >/dev/null
+    target_created=1
+    echo "[agent-branch-merge] Attached worktree for target branch '${TARGET_BRANCH}': ${target_worktree}"
+  fi
+fi
+
+if [[ "$TARGET_BRANCH" == "$BASE_BRANCH" ]]; then
+  echo "[agent-branch-merge] Target branch must not equal the protected base branch '${BASE_BRANCH}'." >&2
+  exit 1
+fi
+
+if ! is_clean_worktree "$target_worktree"; then
+  if [[ "$target_created" -eq 1 ]]; then
+    echo "[agent-branch-merge] Target worktree has freshly generated scaffold changes; continuing inside the new integration lane."
+  else
+    echo "[agent-branch-merge] Target worktree is not clean: ${target_worktree}" >&2
+    echo "[agent-branch-merge] Commit, stash, or discard local changes before merging agent lanes." >&2
+    exit 1
+  fi
+fi
+
+if has_in_progress_git_op "$target_worktree"; then
+  echo "[agent-branch-merge] Target worktree has an in-progress merge/rebase: ${target_worktree}" >&2
+  echo "[agent-branch-merge] Resolve or abort that git operation before running the merge workflow." >&2
+  exit 1
+fi
+
+for source_branch in "${SOURCE_BRANCHES[@]}"; do
+  if [[ "$source_branch" == "$TARGET_BRANCH" ]]; then
+    echo "[agent-branch-merge] Source branch list includes the target branch: ${source_branch}" >&2
+    exit 1
+  fi
+  source_worktree="$(get_worktree_for_branch "$repo_root" "$source_branch")"
+  if [[ -n "$source_worktree" ]] && ! is_clean_worktree "$source_worktree"; then
+    echo "[agent-branch-merge] Source worktree is not clean for '${source_branch}': ${source_worktree}" >&2
+    echo "[agent-branch-merge] Commit or stash source-lane changes before integration." >&2
+    exit 1
+  fi
+done
+
+pending_branches=()
+for source_branch in "${SOURCE_BRANCHES[@]}"; do
+  if git -C "$repo_root" merge-base --is-ancestor "$source_branch" "$TARGET_BRANCH" >/dev/null 2>&1; then
+    echo "[agent-branch-merge] Skipping '${source_branch}' because it is already integrated into '${TARGET_BRANCH}'."
+    continue
+  fi
+  pending_branches+=("$source_branch")
+done
+
+if [[ "${#pending_branches[@]}" -eq 0 ]]; then
+  echo "[agent-branch-merge] No pending source branches remain for target '${TARGET_BRANCH}'."
+  echo "[agent-branch-merge] Target worktree: ${target_worktree}"
+  exit 0
+fi
+
+declare -A file_to_branches=()
+declare -a overlap_files=()
+for source_branch in "${pending_branches[@]}"; do
+  while IFS= read -r changed_file; do
+    [[ -z "$changed_file" ]] && continue
+    existing="${file_to_branches[$changed_file]:-}"
+    if [[ -z "$existing" ]]; then
+      file_to_branches["$changed_file"]="$source_branch"
+      continue
+    fi
+    if [[ ",${existing}," == *",${source_branch},"* ]]; then
+      continue
+    fi
+    file_to_branches["$changed_file"]="${existing},${source_branch}"
+    if ! array_contains "$changed_file" "${overlap_files[@]}"; then
+      overlap_files+=("$changed_file")
+    fi
+  done < <(collect_branch_files "$repo_root" "$start_ref" "$source_branch")
+done
+
+echo "[agent-branch-merge] Target branch: ${TARGET_BRANCH}"
+echo "[agent-branch-merge] Target worktree: ${target_worktree}"
+echo "[agent-branch-merge] Base branch: ${BASE_BRANCH} (${start_ref})"
+echo "[agent-branch-merge] Merge order: ${pending_branches[*]}"
+
+if [[ "${#overlap_files[@]}" -gt 0 ]]; then
+  echo "[agent-branch-merge] Overlapping changed files detected across requested branches:"
+  for overlap_file in "${overlap_files[@]}"; do
+    branches_csv="${file_to_branches[$overlap_file]}"
+    branches_display="$(printf '%s' "$branches_csv" | sed 's/,/, /g')"
+    echo "  - ${overlap_file} <- ${branches_display}"
+  done
+else
+  echo "[agent-branch-merge] No overlapping changed files detected across requested branches."
+fi
+
+for index in "${!pending_branches[@]}"; do
+  source_branch="${pending_branches[$index]}"
+  echo "[agent-branch-merge] Merging '${source_branch}' into '${TARGET_BRANCH}'..."
+  if git -C "$target_worktree" merge --no-ff --no-edit "$source_branch"; then
+    echo "[agent-branch-merge] Merged '${source_branch}'."
+    continue
+  fi
+
+  conflict_files="$(git -C "$target_worktree" diff --name-only --diff-filter=U || true)"
+  echo "[agent-branch-merge] Merge conflict detected while merging '${source_branch}' into '${TARGET_BRANCH}'." >&2
+  echo "[agent-branch-merge] Target worktree: ${target_worktree}" >&2
+  if [[ -n "$conflict_files" ]]; then
+    echo "[agent-branch-merge] Conflicting files:" >&2
+    while IFS= read -r conflict_file; do
+      [[ -n "$conflict_file" ]] && echo "  - ${conflict_file}" >&2
+    done <<< "$conflict_files"
+  fi
+  echo "[agent-branch-merge] Resolve or abort inside the integration worktree:" >&2
+  echo "  cd \"${target_worktree}\"" >&2
+  echo "  git status" >&2
+  echo "  git add <resolved-files> && git commit" >&2
+  echo "  # or: git merge --abort" >&2
+
+  remaining_branches=("${pending_branches[@]:$((index + 1))}")
+  if [[ "${#remaining_branches[@]}" -gt 0 ]]; then
+    echo "[agent-branch-merge] Remaining branches:" >&2
+    for remaining in "${remaining_branches[@]}"; do
+      echo "  - ${remaining}" >&2
+    done
+    resume_cmd="gx merge --into ${TARGET_BRANCH} --base ${BASE_BRANCH}"
+    for remaining in "${remaining_branches[@]}"; do
+      resume_cmd="${resume_cmd} --branch ${remaining}"
+    done
+    echo "[agent-branch-merge] Resume after resolving with: ${resume_cmd}" >&2
+  fi
+  exit 1
+done
+
+echo "[agent-branch-merge] Merge sequence complete for '${TARGET_BRANCH}'."
+if [[ "$target_created" -eq 1 ]]; then
+  echo "[agent-branch-merge] Review and verify in '${target_worktree}', then finish the integration branch when ready."
+fi
+echo "[agent-branch-merge] Next step: bash scripts/agent-branch-finish.sh --branch \"${TARGET_BRANCH}\" --base \"${BASE_BRANCH}\" --via-pr --wait-for-merge --cleanup"

package/templates/scripts/agent-branch-start.sh

@@ -11,6 +11,7 @@ OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
+OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}"
 PRINT_NAME_ONLY=0
 POSITIONAL_ARGS=()
 
@@ -226,13 +227,35 @@ normalize_bool() {
 
 OPENSPEC_AUTO_INIT="$(normalize_bool "$OPENSPEC_AUTO_INIT_RAW" "1")"
 
+resolve_openspec_masterplan_label() {
+  local raw="${OPENSPEC_MASTERPLAN_LABEL_RAW:-}"
+  local label
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ -z "$raw" ]]; then
+    printf ''
+    return 0
+  fi
+
+  label="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
+  printf '%s' "$label"
+}
+
 resolve_openspec_plan_slug() {
   local branch_name="$1"
-  local task_slug="$2"
+  local agent_slug="$2"
+  local task_slug="$3"
+  local masterplan_label=""
+  local branch_leaf=""
   if [[ -n "$OPENSPEC_PLAN_SLUG_OVERRIDE" ]]; then
     sanitize_slug "$OPENSPEC_PLAN_SLUG_OVERRIDE" "$task_slug"
     return 0
   fi
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" == "agent/${agent_slug}/"* ]]; then
+    branch_leaf="${branch_name#agent/${agent_slug}/}"
+    sanitize_slug "agent-${agent_slug}-${masterplan_label}-${branch_leaf}" "$task_slug"
+    return 0
+  fi
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
@@ -255,6 +278,22 @@ resolve_openspec_capability_slug() {
   sanitize_slug "$task_slug" "general-behavior"
 }
 
+resolve_worktree_leaf() {
+  local branch_name="$1"
+  local agent_slug="$2"
+  local masterplan_label=""
+  local branch_leaf=""
+
+  masterplan_label="$(resolve_openspec_masterplan_label)"
+  if [[ -n "$masterplan_label" ]] && [[ "$branch_name" == "agent/${agent_slug}/"* ]]; then
+    branch_leaf="${branch_name#agent/${agent_slug}/}"
+    printf 'agent__%s__%s__%s' "$agent_slug" "$masterplan_label" "$branch_leaf"
+    return 0
+  fi
+
+  printf '%s' "${branch_name//\//__}"
+}
+
 has_local_changes() {
   local root="$1"
   if ! git -C "$root" diff --quiet; then
@@ -497,8 +536,9 @@ done
 
 worktree_root="${repo_root}/${WORKTREE_ROOT_REL}"
 mkdir -p "$worktree_root"
-worktree_path="${worktree_root}/${branch_name//\//__}"
-openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$task_slug")"
+worktree_leaf="$(resolve_worktree_leaf "$branch_name" "$agent_slug")"
+worktree_path="${worktree_root}/${worktree_leaf}"
+openspec_plan_slug="$(resolve_openspec_plan_slug "$branch_name" "$agent_slug" "$task_slug")"
 openspec_change_slug="$(resolve_openspec_change_slug "$branch_name" "$task_slug")"
 openspec_capability_slug="$(resolve_openspec_capability_slug "$task_slug")"