@imdeadpool/guardex 5.0.0

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@imdeadpool/guardex",
+  "version": "5.0.0",
+  "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
+  "license": "MIT",
+  "preferGlobal": true,
+  "bin": {
+    "guardex": "bin/multiagent-safety.js",
+    "gx": "bin/multiagent-safety.js",
+    "musafety": "bin/multiagent-safety.js",
+    "multiagent-safety": "bin/multiagent-safety.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "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:cleanup": "bash ./scripts/agent-worktree-prune.sh --base dev",
+    "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
+    "agent:locks:claim": "python3 ./scripts/agent-file-locks.py claim",
+    "agent:locks:allow-delete": "python3 ./scripts/agent-file-locks.py allow-delete",
+    "agent:locks:release": "python3 ./scripts/agent-file-locks.py release",
+    "agent:locks:status": "python3 ./scripts/agent-file-locks.py status",
+    "agent:plan:init": "bash ./scripts/openspec/init-plan-workspace.sh",
+    "agent:protect:list": "gx protect list",
+    "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:doctor": "gx doctor"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "keywords": [
+    "guardex",
+    "multi-agent",
+    "git-hooks",
+    "branch-guard",
+    "agent-safety",
+    "codex"
+  ],
+  "author": "recodeecom",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/recodeecom/multiagent-safety.git"
+  },
+  "bugs": {
+    "url": "https://github.com/recodeecom/multiagent-safety/issues"
+  },
+  "homepage": "https://github.com/recodeecom/multiagent-safety#readme",
+  "funding": "https://github.com/sponsors/recodeecom",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fast-check": "^3.23.2"
+  }
+}

package/templates/AGENTS.multiagent-safety.md

@@ -0,0 +1,60 @@
+<!-- multiagent-safety:START -->
+## Multi-Agent Execution Contract (multiagent-safety)
+
+0. Session plan comment + read gate (required)
+
+- 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>"`.
+- Agent completion must use `scripts/agent-branch-finish.sh` (direct merge to base when allowed; auto PR fallback for protected bases, then cleanup after merge).
+
+1. Explicit ownership before edits
+
+- Assign each agent clear file/module ownership.
+- Do not edit files outside your assigned scope unless the leader reassigns ownership.
+
+2. Preserve parallel safety
+
+- 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.
+
+3. Verify before completion
+
+- 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 Plan Workspace (recommended)
+
+When work needs a durable planning phase, scaffold a plan workspace before implementation:
+
+```bash
+bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
+```
+
+Expected 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
+```
+<!-- multiagent-safety:END -->

package/templates/claude/commands/guardex.md

@@ -0,0 +1,18 @@
+# /guardex
+
+Run a GuardeX check-and-repair workflow for the current repository.
+
+## 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)
+
+## Style
+
+- Keep output short and operational.
+- Include exact commands you executed.
+- Prefer concrete next actions over generic advice.

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

@@ -0,0 +1,36 @@
+---
+name: guardex
+description: "Use when you need to 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.
+
+## 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.
+
+## Setup path
+
+If guardrails are missing entirely, run:
+
+```sh
+gx setup
+```
+
+Then verify:
+
+```sh
+gx status
+gx scan
+```
+
+## Operator notes
+
+- Prefer `gx doctor` for one-step repair + verification.
+- Keep agent work isolated (`agent/*` branches + lock claims).
+- For one-command Codex sandbox startup, use `bash scripts/codex-agent.sh "<task>" "<agent-name>"`.
+- Do not bypass protected branch safeguards unless explicitly required.

package/templates/githooks/pre-commit

@@ -0,0 +1,178 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
+if [[ -z "$branch" || "$branch" == "HEAD" ]]; then
+  branch="$(git symbolic-ref --quiet --short HEAD 2>/dev/null || true)"
+fi
+if [[ -z "$branch" ]]; then
+  exit 0
+fi
+
+if [[ "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
+  exit 0
+fi
+
+is_unborn_branch=0
+if ! git rev-parse --verify HEAD >/dev/null 2>&1; then
+  is_unborn_branch=1
+fi
+
+is_codex_session=0
+if [[ -n "${CODEX_THREAD_ID:-}" || -n "${OMX_SESSION_ID:-}" || "${CODEX_CI:-0}" == "1" ]]; then
+  is_codex_session=1
+fi
+
+protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
+if [[ -z "$protected_branches_raw" ]]; then
+  protected_branches_raw="dev main master"
+fi
+protected_branches_raw="${protected_branches_raw//,/ }"
+
+is_protected_branch=0
+for protected_branch in $protected_branches_raw; do
+  if [[ "$branch" == "$protected_branch" ]]; then
+    is_protected_branch=1
+    break
+  fi
+done
+
+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"
+fi
+codex_require_agent_branch="$(printf '%s' "$codex_require_agent_branch_raw" | tr '[:upper:]' '[:lower:]')"
+
+should_require_codex_agent_branch=0
+case "$codex_require_agent_branch" in
+  1|true|yes|on) should_require_codex_agent_branch=1 ;;
+  0|false|no|off) should_require_codex_agent_branch=0 ;;
+  *) should_require_codex_agent_branch=1 ;;
+esac
+
+if [[ "$should_require_codex_agent_branch" == "1" && "${MUSAFETY_ALLOW_CODEX_ON_NON_AGENT:-0}" != "1" ]]; then
+  if [[ "$is_codex_session" == "1" && "$branch" != agent/* ]]; then
+    if [[ "$is_protected_branch" == "1" ]]; then
+      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.
+Start the sub-branch/worktree with:
+  bash scripts/codex-agent.sh "<task-or-plan>" "<agent-name>"
+Or manually:
+  bash scripts/agent-branch-start.sh "<task-or-plan>" "<agent-name>"
+Then commit from the created agent/* branch.
+
+Temporary bypass (not recommended):
+  MUSAFETY_ALLOW_CODEX_ON_NON_AGENT=1 git commit ...
+MSG
+      exit 1
+    fi
+
+    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>"
+Then commit from the created agent/* branch.
+
+Temporary bypass (not recommended):
+  MUSAFETY_ALLOW_CODEX_ON_NON_AGENT=1 git commit ...
+Disable this rule for a repo (not recommended):
+  git config multiagent.codexRequireAgentBranch false
+MSG
+    exit 1
+  fi
+fi
+
+if [[ "$is_protected_branch" == "1" ]]; then
+  if [[ "$is_unborn_branch" == "1" && "$is_codex_session" != "1" ]]; then
+    exit 0
+  fi
+
+  git_dir="$(git rev-parse --git-dir)"
+  if [[ -f "$git_dir/MERGE_HEAD" ]]; then
+    exit 0
+  fi
+
+  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>"
+After finishing work:
+  bash scripts/agent-branch-finish.sh
+
+Temporary bypass (not recommended):
+  ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
+MSG
+  exit 1
+fi
+
+if [[ "$branch" == agent/* ]]; then
+  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.
+Claim files first:
+  python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
+MSG
+    exit 1
+  fi
+
+  require_sync_before_commit_raw="$(git config --get multiagent.sync.requireBeforeCommit || true)"
+  if [[ -z "$require_sync_before_commit_raw" ]]; then
+    require_sync_before_commit_raw="false"
+  fi
+  require_sync_before_commit="$(printf '%s' "$require_sync_before_commit_raw" | tr '[:upper:]' '[:lower:]')"
+
+  should_require_sync=0
+  case "$require_sync_before_commit" in
+    1|true|yes|on) should_require_sync=1 ;;
+    0|false|no|off) should_require_sync=0 ;;
+    *) should_require_sync=0 ;;
+  esac
+
+  if [[ "$should_require_sync" == "1" ]]; then
+    base_branch="$(git config --get multiagent.baseBranch || true)"
+    if [[ -z "$base_branch" ]]; then
+      base_branch="dev"
+    fi
+
+    max_behind_raw="$(git config --get multiagent.sync.maxBehindCommits || true)"
+    if [[ -z "$max_behind_raw" ]]; then
+      max_behind_raw="0"
+    fi
+    if [[ ! "$max_behind_raw" =~ ^[0-9]+$ ]]; then
+      echo "[agent-sync-guard] Invalid multiagent.sync.maxBehindCommits value: ${max_behind_raw}" >&2
+      echo "[agent-sync-guard] Expected non-negative integer. Example: git config multiagent.sync.maxBehindCommits 0" >&2
+      exit 1
+    fi
+
+    if ! git fetch origin "$base_branch" --quiet >/dev/null 2>&1; then
+      echo "[agent-sync-guard] Unable to fetch origin/${base_branch} while commit sync gate is enabled." >&2
+      echo "[agent-sync-guard] Disable gate temporarily with: git config multiagent.sync.requireBeforeCommit false" >&2
+      exit 1
+    fi
+
+    if ! git show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
+      echo "[agent-sync-guard] Remote base branch not found: origin/${base_branch}" >&2
+      exit 1
+    fi
+
+    behind_count="$(git rev-list --left-right --count "${branch}...origin/${base_branch}" 2>/dev/null | awk '{print $2}')"
+    behind_count="${behind_count:-0}"
+    max_behind="${max_behind_raw}"
+
+    if [[ "$behind_count" -gt "$max_behind" ]]; then
+      cat >&2 <<MSG
+[agent-sync-guard] Commit blocked: '${branch}' is behind origin/${base_branch} by ${behind_count} commit(s) (max allowed: ${max_behind}).
+Run:
+  gx sync --base ${base_branch}
+Or relax threshold:
+  git config multiagent.sync.maxBehindCommits <n>
+MSG
+      exit 1
+    fi
+  fi
+fi
+
+if command -v pre-commit >/dev/null 2>&1 && [[ -f .pre-commit-config.yaml ]]; then
+  pre-commit run --hook-stage pre-commit
+fi

package/templates/githooks/pre-push

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${ALLOW_PUSH_ON_PROTECTED_BRANCH:-0}" == "1" || "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
+  exit 0
+fi
+
+is_vscode_git_context=0
+if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" ]]; then
+  is_vscode_git_context=1
+fi
+
+if [[ "$is_vscode_git_context" == "1" ]]; then
+  exit 0
+fi
+
+protected_branches_raw="${MUSAFETY_PROTECTED_BRANCHES:-$(git config --get multiagent.protectedBranches || true)}"
+if [[ -z "$protected_branches_raw" ]]; then
+  protected_branches_raw="dev main master"
+fi
+protected_branches_raw="${protected_branches_raw//,/ }"
+
+is_protected_branch() {
+  local branch="$1"
+  for protected_branch in $protected_branches_raw; do
+    if [[ "$branch" == "$protected_branch" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+blocked_refs=()
+while IFS=' ' read -r local_ref local_sha remote_ref remote_sha; do
+  if [[ -z "${remote_ref:-}" || "$remote_ref" != refs/heads/* ]]; then
+    continue
+  fi
+
+  remote_branch="${remote_ref#refs/heads/}"
+  if is_protected_branch "$remote_branch"; then
+    blocked_refs+=("$remote_branch")
+  fi
+done
+
+if [[ "${#blocked_refs[@]}" -gt 0 ]]; then
+  {
+    echo "[agent-branch-guard] Push to protected branch blocked outside VS Code Git context."
+    echo "[agent-branch-guard] Protected target(s): ${blocked_refs[*]}"
+    echo "[agent-branch-guard] Use VS Code Source Control for protected-branch push, or push from an agent branch and merge via PR."
+    echo
+    echo "Temporary bypass (not recommended):"
+    echo "  ALLOW_PUSH_ON_PROTECTED_BRANCH=1 git push ..."
+  } >&2
+  exit 1
+fi
+
+exit 0