@imdeadpool/guardex 5.0.12 → 5.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.12",
+  "version": "5.0.15",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/AGENTS.multiagent-safety.md

@@ -16,8 +16,8 @@
 - 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>" --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 --via-pr` until merged.
+- 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.
@@ -46,12 +46,13 @@
 - Verification commands + results
 - Risks / follow-ups
 
-## OpenSpec Plan Workspace (required for agent sub-branch changes)
+## OpenSpec Workspaces (required for agent sub-branch changes)
 
-OMX Codex execution flows must use OpenSpec. `scripts/codex-agent.sh` bootstraps a
-per-branch plan workspace automatically under:
+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>/
 ```
 
@@ -59,10 +60,21 @@ For manual `scripts/agent-branch-start.sh` usage, enable auto-bootstrap with
 `MUSAFETY_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 shape:
+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>/

package/templates/githooks/post-merge

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${MUSAFETY_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="${MUSAFETY_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="${MUSAFETY_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

@@ -30,7 +30,7 @@ fi
 
 allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
 if [[ -z "$allow_vscode_protected_raw" ]]; then
-  allow_vscode_protected_raw="true"
+  allow_vscode_protected_raw="false"
 fi
 allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
 
@@ -55,15 +55,6 @@ for protected_branch in $protected_branches_raw; do
   fi
 done
 
-is_local_only_branch=0
-if [[ "$is_protected_branch" == "1" ]]; then
-  upstream_ref="$(git for-each-ref --format='%(upstream:short)' "refs/heads/${branch}" | head -n 1)"
-  remote_branch_ref="$(git for-each-ref --format='%(refname:short)' "refs/remotes/*/${branch}" | head -n 1)"
-  if [[ -z "$upstream_ref" && -z "$remote_branch_ref" ]]; then
-    is_local_only_branch=1
-  fi
-fi
-
 codex_require_agent_branch_raw="${MUSAFETY_CODEX_REQUIRE_AGENT_BRANCH:-$(git config --get multiagent.codexRequireAgentBranch || true)}"
 if [[ -z "$codex_require_agent_branch_raw" ]]; then
   codex_require_agent_branch_raw="true"
@@ -134,7 +125,7 @@ fi
 
 if [[ "$is_protected_branch" == "1" ]]; then
   if [[ "$is_codex_session" != "1" && "$is_vscode_git_context" == "1" ]]; then
-    if [[ "$allow_vscode_protected_branch_writes" == "1" || "$is_local_only_branch" == "1" ]]; then
+    if [[ "$allow_vscode_protected_branch_writes" == "1" ]]; then
       exit 0
     fi
   fi
@@ -155,11 +146,21 @@ Use an agent branch first:
 After finishing work:
   bash scripts/agent-branch-finish.sh
 
-Optional repo hard-block for VS Code protected-branch commits:
-  git config multiagent.allowVscodeProtectedBranchWrites false
+Optional repo opt-in for VS Code protected-branch commits:
+  git config multiagent.allowVscodeProtectedBranchWrites true
+
+Temporary bypass (not recommended):
+  ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
+MSG
+  exit 1
+fi
 
-VS Code Source Control commits on protected local-only branches
-(no upstream and no remote branch) are allowed automatically.
+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 ...
@@ -168,6 +169,14 @@ MSG
 fi
 
 if [[ "$branch" == agent/* ]]; then
+  if [[ "${MUSAFETY_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
     cat >&2 <<'MSG'
 [agent-branch-guard] Agent branch commits require file ownership locks.

package/templates/githooks/pre-push

@@ -12,7 +12,7 @@ fi
 
 allow_vscode_protected_raw="${MUSAFETY_ALLOW_VSCODE_PROTECTED_BRANCH_WRITES:-$(git config --get multiagent.allowVscodeProtectedBranchWrites || true)}"
 if [[ -z "$allow_vscode_protected_raw" ]]; then
-  allow_vscode_protected_raw="true"
+  allow_vscode_protected_raw="false"
 fi
 allow_vscode_protected="$(printf '%s' "$allow_vscode_protected_raw" | tr '[:upper:]' '[:lower:]')"
 
@@ -77,8 +77,8 @@ if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
     echo "[agent-branch-guard] Push to protected branch blocked."
     echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"
     echo "[agent-branch-guard] Use an agent branch and merge via PR."
-    echo "[agent-branch-guard] Optional repo hard-block for VS Code protected-branch push:"
-    echo "  git config multiagent.allowVscodeProtectedBranchWrites false"
+    echo "[agent-branch-guard] Optional repo opt-in for VS Code protected-branch push:"
+    echo "  git config multiagent.allowVscodeProtectedBranchWrites true"
     echo
     echo "Temporary bypass (not recommended):"
     echo "  ALLOW_PUSH_ON_PROTECTED_BRANCH=1 git push ..."

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

@@ -162,28 +162,6 @@ if [[ "$BASE_BRANCH_EXPLICIT" -eq 0 ]]; then
   fi
 fi
 
-if [[ -z "$BASE_BRANCH" ]]; then
-  branch_stored_base="$(git -C "$repo_root" config --get "branch.${SOURCE_BRANCH}.musafetyBase" || true)"
-  if [[ -n "$branch_stored_base" ]]; then
-    BASE_BRANCH="$branch_stored_base"
-  fi
-fi
-
-if [[ -z "$BASE_BRANCH" ]]; then
-  source_upstream="$(git -C "$repo_root" for-each-ref --format='%(upstream:short)' "refs/heads/${SOURCE_BRANCH}" | head -n 1)"
-  source_upstream="${source_upstream:-}"
-  if [[ "$source_upstream" == */* ]]; then
-    BASE_BRANCH="${source_upstream#*/}"
-  fi
-fi
-
-if [[ -z "$BASE_BRANCH" ]]; then
-  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-  if [[ -n "$current_branch" && "$current_branch" != "HEAD" && "$current_branch" != "$SOURCE_BRANCH" ]]; then
-    BASE_BRANCH="$current_branch"
-  fi
-fi
-
 if [[ -z "$BASE_BRANCH" ]]; then
   BASE_BRANCH="dev"
 fi

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

@@ -8,6 +8,8 @@ BASE_BRANCH_EXPLICIT=0
 WORKTREE_ROOT_REL=".omx/agent-worktrees"
 OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-false}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
+OPENSPEC_CHANGE_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_CHANGE_SLUG:-}"
+OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_CAPABILITY_SLUG:-}"
 POSITIONAL_ARGS=()
 
 while [[ $# -gt 0 ]]; do
@@ -109,6 +111,25 @@ resolve_openspec_plan_slug() {
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
+resolve_openspec_change_slug() {
+  local branch_name="$1"
+  local task_slug="$2"
+  if [[ -n "$OPENSPEC_CHANGE_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_CHANGE_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
+resolve_openspec_capability_slug() {
+  local task_slug="$1"
+  if [[ -n "$OPENSPEC_CAPABILITY_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_CAPABILITY_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "$task_slug" "general-behavior"
+}
+
 resolve_active_codex_snapshot_name() {
   local override="${MUSAFETY_CODEX_AUTH_SNAPSHOT:-}"
   if [[ -n "$override" ]]; then
@@ -250,6 +271,44 @@ initialize_openspec_plan_workspace() {
   echo "[agent-branch-start] OpenSpec plan workspace: ${worktree}/openspec/plan/${plan_slug}"
 }
 
+initialize_openspec_change_workspace() {
+  local repo="$1"
+  local worktree="$2"
+  local change_slug="$3"
+  local capability_slug="$4"
+
+  hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-change-workspace.sh"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  local openspec_script="${worktree}/scripts/openspec/init-change-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[agent-branch-start] OpenSpec change init script is missing in sandbox worktree." >&2
+    echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local init_output=""
+  if ! init_output="$(
+    cd "$worktree"
+    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
+    return 1
+  fi
+
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[agent-branch-start] OpenSpec change workspace: ${worktree}/openspec/changes/${change_slug}"
+}
+
 if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   echo "[agent-branch-start] Not inside a git repository." >&2
   exit 1
@@ -312,6 +371,8 @@ 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")"
+openspec_change_slug="$(resolve_openspec_change_slug "$branch_name" "$task_slug")"
+openspec_capability_slug="$(resolve_openspec_capability_slug "$task_slug")"
 
 if [[ -e "$worktree_path" ]]; then
   echo "[agent-branch-start] Worktree path already exists: ${worktree_path}" >&2
@@ -364,15 +425,19 @@ hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-ag
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules"
 hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules"
+if ! initialize_openspec_change_workspace "$repo_root" "$worktree_path" "$openspec_change_slug" "$openspec_capability_slug"; then
+  exit 1
+fi
 if ! initialize_openspec_plan_workspace "$repo_root" "$worktree_path" "$openspec_plan_slug"; then
   exit 1
 fi
 
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
+echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
 echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"
 echo "[agent-branch-start] Next steps:"
 echo "  cd \"${worktree_path}\""
 echo "  python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" <file...>"
 echo "  # implement + commit"
-echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\""
+echo "  bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base dev --via-pr --wait-for-merge"

package/templates/scripts/codex-agent.sh

@@ -12,6 +12,8 @@ AUTO_CLEANUP_RAW="${MUSAFETY_CODEX_AUTO_CLEANUP:-true}"
 AUTO_WAIT_FOR_MERGE_RAW="${MUSAFETY_CODEX_WAIT_FOR_MERGE:-true}"
 OPENSPEC_AUTO_INIT_RAW="${MUSAFETY_OPENSPEC_AUTO_INIT:-true}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_PLAN_SLUG:-}"
+OPENSPEC_CHANGE_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_CHANGE_SLUG:-}"
+OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${MUSAFETY_OPENSPEC_CAPABILITY_SLUG:-}"
 
 normalize_bool() {
   local raw="${1:-}"
@@ -150,6 +152,27 @@ resolve_openspec_plan_slug() {
   sanitize_slug "${branch_name//\//-}" "$task_slug"
 }
 
+resolve_openspec_change_slug() {
+  local branch_name="$1"
+  local task_slug
+  task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+  if [[ -n "$OPENSPEC_CHANGE_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_CHANGE_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "${branch_name//\//-}" "$task_slug"
+}
+
+resolve_openspec_capability_slug() {
+  local task_slug
+  task_slug="$(sanitize_slug "$TASK_NAME" "task")"
+  if [[ -n "$OPENSPEC_CAPABILITY_SLUG_OVERRIDE" ]]; then
+    sanitize_slug "$OPENSPEC_CAPABILITY_SLUG_OVERRIDE" "$task_slug"
+    return 0
+  fi
+  sanitize_slug "$task_slug" "general-behavior"
+}
+
 hydrate_local_helper_in_worktree() {
   local worktree="$1"
   local relative_path="$2"
@@ -192,13 +215,6 @@ resolve_start_base_branch() {
     return 0
   fi
 
-  local current_branch
-  current_branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-  if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
-    printf '%s' "$current_branch"
-    return 0
-  fi
-
   printf 'dev'
 }
 
@@ -338,30 +354,20 @@ has_origin_remote() {
 }
 
 resolve_worktree_base_branch() {
-  local wt="$1"
+  local _wt="$1"
   if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
     printf '%s' "$BASE_BRANCH"
     return 0
   fi
 
-  local branch
-  branch="$(git -C "$wt" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
-  if [[ -z "$branch" || "$branch" == "HEAD" ]]; then
-    return 0
-  fi
-
-  local stored_base
-  stored_base="$(git -C "$repo_root" config --get "branch.${branch}.musafetyBase" || true)"
-  if [[ -n "$stored_base" ]]; then
-    printf '%s' "$stored_base"
-    return 0
-  fi
-
   local configured_base
   configured_base="$(git -C "$repo_root" config --get multiagent.baseBranch || true)"
   if [[ -n "$configured_base" ]]; then
     printf '%s' "$configured_base"
+    return 0
   fi
+
+  printf 'dev'
 }
 
 sync_worktree_with_base() {
@@ -443,6 +449,43 @@ ensure_openspec_plan_workspace() {
   echo "[codex-agent] OpenSpec plan workspace: ${wt}/openspec/plan/${plan_slug}"
 }
 
+ensure_openspec_change_workspace() {
+  local wt="$1"
+  local branch="$2"
+
+  if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+    return 0
+  fi
+
+  hydrate_local_helper_in_worktree "$wt" "scripts/openspec/init-change-workspace.sh"
+
+  local openspec_script="${wt}/scripts/openspec/init-change-workspace.sh"
+  if [[ ! -f "$openspec_script" ]]; then
+    echo "[codex-agent] Missing OpenSpec change init script in sandbox: ${openspec_script}" >&2
+    echo "[codex-agent] Run 'gx setup --target ${repo_root}' and retry." >&2
+    return 1
+  fi
+  if [[ ! -x "$openspec_script" ]]; then
+    chmod +x "$openspec_script" 2>/dev/null || true
+  fi
+
+  local change_slug capability_slug init_output=""
+  change_slug="$(resolve_openspec_change_slug "$branch")"
+  capability_slug="$(resolve_openspec_capability_slug)"
+  if ! init_output="$(
+    cd "$wt"
+    bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1
+  )"; then
+    printf '%s\n' "$init_output" >&2
+    echo "[codex-agent] OpenSpec workspace initialization failed for change '${change_slug}'." >&2
+    return 1
+  fi
+  if [[ -n "$init_output" ]]; then
+    printf '%s\n' "$init_output"
+  fi
+  echo "[codex-agent] OpenSpec change workspace: ${wt}/openspec/changes/${change_slug}"
+}
+
 worktree_has_changes() {
   local wt="$1"
   if ! git -C "$wt" diff --quiet -- . ":(exclude).omx/state/agent-file-locks.json"; then
@@ -598,12 +641,18 @@ looks_like_conflict_failure() {
 run_finish_flow() {
   local wt="$1"
   local branch="$2"
+  local finish_base_branch=""
   local finish_output=""
   local -a finish_args
 
   finish_args=(--branch "$branch")
-  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 ]]; then
-    finish_args+=(--base "$BASE_BRANCH")
+  if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -n "$BASE_BRANCH" ]]; then
+    finish_base_branch="$BASE_BRANCH"
+  else
+    finish_base_branch="$(resolve_worktree_base_branch "$wt")"
+  fi
+  if [[ -n "$finish_base_branch" ]]; then
+    finish_args+=(--base "$finish_base_branch")
   fi
   if [[ "$AUTO_CLEANUP" -eq 1 ]]; then
     finish_args+=(--cleanup)
@@ -613,9 +662,11 @@ run_finish_flow() {
   fi
 
   if has_origin_remote; then
-    if command -v gh >/dev/null 2>&1 || command -v "${MUSAFETY_GH_BIN:-gh}" >/dev/null 2>&1; then
-      finish_args+=(--via-pr)
+    if ! command -v "${MUSAFETY_GH_BIN:-gh}" >/dev/null 2>&1 && ! command -v gh >/dev/null 2>&1; then
+      echo "[codex-agent] Auto-finish requires GitHub CLI for PR flow; command not found: ${MUSAFETY_GH_BIN:-gh}" >&2
+      return 2
     fi
+    finish_args+=(--via-pr)
   else
     echo "[codex-agent] No origin remote detected; skipping auto-finish merge/PR pipeline." >&2
     return 2
@@ -631,7 +682,7 @@ run_finish_flow() {
   if [[ "$AUTO_REVIEW_ON_CONFLICT" -eq 1 ]] && looks_like_conflict_failure "$finish_output"; then
     echo "[codex-agent] Auto-finish hit conflicts. Launching Codex conflict-review pass in sandbox..." >&2
     local review_prompt
-    review_prompt="Resolve git conflicts for branch ${branch} against ${BASE_BRANCH:-base branch}, then commit the resolution in this sandbox worktree and exit."
+    review_prompt="Resolve git conflicts for branch ${branch} against ${finish_base_branch:-dev}, then commit the resolution in this sandbox worktree and exit."
 
     (
       cd "$wt"
@@ -665,6 +716,10 @@ if [[ -z "$worktree_branch" || "$worktree_branch" == "HEAD" ]]; then
   exit 1
 fi
 
+if ! ensure_openspec_change_workspace "$worktree_path" "$worktree_branch"; then
+  exit 1
+fi
+
 if ! ensure_openspec_plan_workspace "$worktree_path" "$worktree_branch"; then
   exit 1
 fi
@@ -735,7 +790,7 @@ else
     if [[ "$auto_finish_completed" -eq 1 ]]; then
       echo "[codex-agent] Branch kept intentionally. Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     else
-      echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --via-pr"
+      echo "[codex-agent] If finished, merge with: bash scripts/agent-branch-finish.sh --branch \"${worktree_branch}\" --base dev --via-pr --wait-for-merge"
       echo "[codex-agent] Cleanup on demand: gx cleanup --branch \"${worktree_branch}\""
     fi
   fi

package/templates/scripts/openspec/init-change-workspace.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 || $# -gt 2 ]]; then
+  echo "Usage: $0 <change-slug> [capability-slug]"
+  echo "Example: $0 add-dashboard-live-usage runtime-migration"
+  exit 1
+fi
+
+CHANGE_SLUG="$1"
+CAPABILITY_SLUG="${2:-$CHANGE_SLUG}"
+
+if [[ "$CHANGE_SLUG" =~ [^a-z0-9-] ]]; then
+  echo "Error: change slug must be kebab-case (lowercase letters, numbers, hyphens)."
+  exit 1
+fi
+
+if [[ "$CAPABILITY_SLUG" =~ [^a-z0-9-] ]]; then
+  echo "Error: capability slug must be kebab-case (lowercase letters, numbers, hyphens)."
+  exit 1
+fi
+
+CHANGE_DIR="openspec/changes/${CHANGE_SLUG}"
+SPEC_DIR="${CHANGE_DIR}/specs/${CAPABILITY_SLUG}"
+TODAY="$(date -u +%Y-%m-%d)"
+
+mkdir -p "$SPEC_DIR"
+
+if [[ ! -f "${CHANGE_DIR}/.openspec.yaml" ]]; then
+  cat > "${CHANGE_DIR}/.openspec.yaml" <<YAMLEOF
+schema: spec-driven
+created: ${TODAY}
+YAMLEOF
+fi
+
+if [[ ! -f "${CHANGE_DIR}/proposal.md" ]]; then
+  cat > "${CHANGE_DIR}/proposal.md" <<PROPOSALEOF
+## Why
+
+- TODO: describe the user/problem outcome this change addresses.
+
+## What Changes
+
+- TODO: summarize the intended behavior and scope.
+
+## Impact
+
+- TODO: call out risks, rollout notes, and affected surfaces.
+PROPOSALEOF
+fi
+
+if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
+  cat > "${CHANGE_DIR}/tasks.md" <<TASKSEOF
+## 1. Specification
+
+- [ ] 1.1 Finalize proposal scope and acceptance criteria for \`${CHANGE_SLUG}\`.
+- [ ] 1.2 Define normative requirements in \`specs/${CAPABILITY_SLUG}/spec.md\`.
+
+## 2. Implementation
+
+- [ ] 2.1 Implement scoped behavior changes.
+- [ ] 2.2 Add/update focused regression coverage.
+
+## 3. Verification
+
+- [ ] 3.1 Run targeted project verification commands.
+- [ ] 3.2 Run \`openspec validate ${CHANGE_SLUG} --type change --strict\`.
+- [ ] 3.3 Run \`openspec validate --specs\`.
+TASKSEOF
+fi
+
+if [[ ! -f "${SPEC_DIR}/spec.md" ]]; then
+  cat > "${SPEC_DIR}/spec.md" <<SPECEOF
+## ADDED Requirements
+
+### Requirement: ${CAPABILITY_SLUG} behavior
+The system SHALL enforce ${CAPABILITY_SLUG} behavior as defined by this change.
+
+#### Scenario: Baseline acceptance
+- **WHEN** ${CAPABILITY_SLUG} behavior is exercised
+- **THEN** the expected outcome is produced
+- **AND** regressions are covered by tests.
+SPECEOF
+fi
+
+echo "[guardex] OpenSpec change workspace ready: ${CHANGE_DIR}"
+echo "[guardex] OpenSpec change spec scaffold: ${SPEC_DIR}/spec.md"