@imdeadpool/guardex 5.0.11 → 5.0.12

package/README.md

@@ -1,8 +1,8 @@
 # GuardeX — Guardian T-Rex for your repo
 
 [![npm version](https://img.shields.io/npm/v/%40imdeadpool%2Fguardex?color=cb3837&logo=npm)](https://www.npmjs.com/package/@imdeadpool/guardex)
-[![CI](https://github.com/recodeecom/multiagent-safety/actions/workflows/ci.yml/badge.svg)](https://github.com/recodeecom/multiagent-safety/actions/workflows/ci.yml)
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/recodeecom/multiagent-safety/badge)](https://securityscorecards.dev/viewer/?uri=github.com/recodeecom/multiagent-safety)
+[![CI](https://github.com/recodeee/guardex/actions/workflows/ci.yml/badge.svg)](https://github.com/recodeee/guardex/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/recodeee/guardex/badge)](https://securityscorecards.dev/viewer/?uri=github.com/recodeee/guardex)
 
 GuardeX is a safety layer for parallel Codex/agent work in git repos.
 
@@ -17,7 +17,7 @@ Progress became **de-progressive**: more activity, less real forward movement.
 
 GuardeX exists to stop that loop.
 
-![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/dashboard-multi-agent.png)
+![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/dashboard-multi-agent.png)
 
 ```mermaid
 flowchart LR
@@ -81,23 +81,23 @@ gx finish --all
 
 ### Setup status
 
-![gx setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
+![gx setup behavior screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/setup-success.svg)
 
 ### Service logs/status
 
-![gx status logs screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/status-tools-logs.svg)
+![gx status logs screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/status-tools-logs.svg)
 
 ### Branch/worktree start protocol
 
-![gx branch start protocol screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-branch-start.svg)
+![gx branch start protocol screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-branch-start.svg)
 
 ### Lock + delete guard protocol
 
-![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-lock-guard.svg)
+![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-lock-guard.svg)
 
 ### Real VS Code Source Control layout (exact screenshot)
 
-![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-vscode-source-control-exact.png)
+![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-vscode-source-control-exact.png)
 
 ## Copy-paste: common commands
 
@@ -141,7 +141,7 @@ gx cleanup --watch --interval 60
 
 # scan/report
 gx scan
-gx report scorecard --repo github.com/recodeecom/multiagent-safety
+gx report scorecard --repo github.com/recodeee/guardex
 ```
 
 ### Continuous Codex PR monitor (local codex-auth session)
@@ -241,6 +241,40 @@ gh --version
 gh auth status
 ```
 
+## Optional GitHub Apps: fork sync + PR review
+
+### Pull app (Probot fork sync)
+
+GuardeX setup now installs a starter file at `.github/pull.yml.example`.
+
+To enable fork auto-sync:
+
+```sh
+cp .github/pull.yml.example .github/pull.yml
+```
+
+Then edit `.github/pull.yml`:
+
+- set `rules[].base` to your fork branch (`main`, `master`, or `dev`)
+- set `rules[].upstream` to `<upstream-owner>:<branch>`
+
+Install the app: <https://github.com/apps/pull>  
+Validate config: `https://pull.git.ci/check/<owner>/<repo>`
+
+### CR-GPT code review app
+
+Install app: <https://github.com/apps/cr-gpt>
+
+`gx setup` also installs `.github/workflows/cr.yml` (GitHub Actions review workflow).
+
+Then in your repo:
+
+1. `Settings -> Secrets and variables -> Actions`
+2. open `Variables`
+3. add `OPENAI_API_KEY`
+
+After that, the app reviews new and updated pull requests automatically.
+
 ## Companion dependency: `codex-auth` account switcher
 
 For multi-identity Codex workflows, GuardeX pairs with
@@ -276,6 +310,8 @@ scripts/openspec/init-plan-workspace.sh
 .githooks/pre-push
 .codex/skills/guardex/SKILL.md
 .claude/commands/guardex.md
+.github/pull.yml.example
+.github/workflows/cr.yml
 .omx/state/agent-file-locks.json
 ```
 
@@ -328,6 +364,11 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.12
+
+- Bumped package version from `5.0.11` to `5.0.12` for the next npm publish.
+- Updated repository metadata and README links to the renamed GitHub repository (`recodeee/guardex`).
+
 ### v5.0.11
 
 - Updated the managed AGENTS contract wording to use `GX` naming and added an explicit OMX completion policy requiring commit + push + PR creation/update at task completion.

package/bin/multiagent-safety.js

@@ -50,7 +50,10 @@ const TEMPLATE_FILES = [
   'githooks/pre-commit',
   'githooks/pre-push',
   'codex/skills/guardex/SKILL.md',
+  'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   'claude/commands/guardex.md',
+  'github/pull.yml.example',
+  'github/workflows/cr.yml',
 ];
 
 const EXECUTABLE_RELATIVE_PATHS = new Set([
@@ -97,6 +100,7 @@ const MANAGED_GITIGNORE_PATHS = [
   '.githooks/pre-push',
   'oh-my-codex/',
   '.codex/skills/guardex/SKILL.md',
+  '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   '.claude/commands/guardex.md',
   LOCK_FILE_RELATIVE,
 ];
@@ -230,6 +234,25 @@ const AI_SETUP_PROMPT = `Use this exact checklist to setup GuardeX (Guardian T-R
 
 11) Optional (GitHub remote cleanup): enable:
    Settings -> General -> Pull Requests -> Automatically delete head branches
+
+12) Optional (fork sync with Pull app):
+   cp .github/pull.yml.example .github/pull.yml
+   # then edit .github/pull.yml:
+   # - set rules[].base to your fork branch (main/master/dev)
+   # - set rules[].upstream to upstream-owner:branch
+   # install app: https://github.com/apps/pull
+   # validate config: https://pull.git.ci/check/<owner>/<repo>
+
+13) Optional (PR review bot with cr-gpt GitHub App):
+   - install app: https://github.com/apps/cr-gpt
+   - in GitHub repo Settings -> Secrets and variables -> Actions -> Variables:
+     add OPENAI_API_KEY (your API key)
+   - the app reviews new/updated pull requests automatically
+
+14) Optional: test PR review action workflow
+   - gx setup installs .github/workflows/cr.yml
+   - open or update a PR
+   - check Actions -> "Code Review" run logs + PR timeline comments
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -249,6 +272,7 @@ openspec update
 gx protect add release staging
 gx sync --check
 gx sync
+cp .github/pull.yml.example .github/pull.yml
 `;
 
 const SCORECARD_RISK_BY_CHECK = {
@@ -452,6 +476,9 @@ function toDestinationPath(relativeTemplatePath) {
   if (relativeTemplatePath.startsWith('claude/')) {
     return `.${relativeTemplatePath}`;
   }
+  if (relativeTemplatePath.startsWith('github/')) {
+    return `.${relativeTemplatePath}`;
+  }
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "5.0.11",
+  "version": "5.0.12",
   "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

@@ -19,7 +19,7 @@
 - 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.
 - 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.
 

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/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