@imdeadpool/guardex 5.0.11 → 5.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.11",
+  "version": "5.0.13",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -54,12 +54,12 @@
   "author": "recodeecom",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/recodeecom/multiagent-safety.git"
+    "url": "git+https://github.com/recodeee/guardex.git"
   },
   "bugs": {
-    "url": "https://github.com/recodeecom/multiagent-safety/issues"
+    "url": "https://github.com/recodeee/guardex/issues"
   },
-  "homepage": "https://github.com/recodeecom/multiagent-safety#readme",
+  "homepage": "https://github.com/recodeee/guardex#readme",
   "funding": "https://github.com/sponsors/recodeecom",
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.multiagent-safety.md

@@ -16,10 +16,10 @@
 - 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, 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`.
+- 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.
 
@@ -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/codex/skills/guardex/SKILL.md

@@ -38,4 +38,52 @@ gx scan
 - 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.
+
+## Bulk merge runbook (changed agent branches)
+
+Use this when a repo has many `agent/*` branches/worktrees with pending changes and you need them merged into the base branch quickly.
+
+1. Confirm base and guardrails are healthy:
+
+```sh
+git status --short --branch
+git pull --ff-only origin "$(git config --get multiagent.baseBranch || echo dev)"
+gx scan
+```
+
+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:
+
+```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
+```

package/templates/codex/skills/guardex-merge-skills-to-dev/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: guardex-merge-skills-to-dev
+description: "Use when you need to merge SKILL.md updates from agent branches/worktrees into the local base branch (default: dev) with the multiagent-safety flow."
+---
+
+# GuardeX Merge Skills to dev
+
+Use this skill when you only want to promote Codex skill file updates into the base branch (normally `dev`) without editing the visible base checkout directly.
+
+## What this merges
+
+- `.codex/skills/**/SKILL.md`
+- `templates/codex/skills/**/SKILL.md`
+
+## Merge runbook (safe path)
+
+1. Resolve the base branch:
+
+```sh
+BASE_BRANCH="$(git config --get multiagent.baseBranch || echo dev)"
+echo "$BASE_BRANCH"
+```
+
+2. Start a dedicated integration sandbox from base:
+
+```sh
+bash scripts/agent-branch-start.sh "merge-skill-files-to-${BASE_BRANCH}" "skill-merge" "$BASE_BRANCH"
+```
+
+3. Enter the sandbox worktree printed by the command above.
+
+4. Pull only skill files from each source agent branch:
+
+```sh
+SOURCE_BRANCH="<agent-branch>"
+git checkout "$SOURCE_BRANCH" -- ':(glob).codex/skills/**/SKILL.md' ':(glob)templates/codex/skills/**/SKILL.md'
+```
+
+5. Verify scope before commit:
+
+```sh
+git status --short
+git diff --name-only
+```
+
+6. Commit and merge back to base using guardex finish flow:
+
+```sh
+git add .codex/skills templates/codex/skills
+git commit -m "Merge skill file updates into ${BASE_BRANCH}"
+bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)" --base "$BASE_BRANCH" --via-pr --wait-for-merge --cleanup
+```
+
+## Notes
+
+- If a source branch has non-skill changes, this runbook keeps them out of the merge.
+- If merge conflicts occur, resolve only within the skill files, then rerun `agent-branch-finish.sh`.
+- Do not commit directly on `dev`/`main`; always merge through an agent branch/worktree.

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/github/pull.yml.example

@@ -0,0 +1,6 @@
+version: "1"
+rules:
+  - base: main
+    upstream: upstream-owner:main
+    mergeMethod: hardreset
+    mergeUnstable: true

package/templates/github/workflows/cr.yml

@@ -0,0 +1,21 @@
+name: Code Review
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  review:
+    if: ${{ secrets.OPENAI_API_KEY != '' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: anc95/ChatGPT-CodeReview@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_API_ENDPOINT: https://api.openai.com/v1
+          MODEL: gpt-4o-mini

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"