@imdeadpool/guardex 5.0.2 → 5.0.4

package/CONTRIBUTING.md

@@ -23,3 +23,4 @@ npm pack --dry-run
 - Keep `main` green (CI passing)
 - Prefer trusted publishing (`npm publish --provenance`)
 - Use a clean working tree and tag-based releases when possible
+- When version changes, update `README.md` release notes in the same PR/commit

package/README.md

@@ -4,405 +4,229 @@
 [![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)
 
-GuardeX is a short-command, hardened multi-agent safety setup for any git repo.
+GuardeX is a safety layer for parallel Codex/agent work in git repos.
 
 > [!WARNING]
 > Not affiliated with OpenAI or Codex. Not an official tool.
 
-## Why this tool exists
+## The problem (what was going wrong)
 
-If you run multiple agents at the same time, it is easy to get collisions:
-two agents editing the same files, unsafe deletes, broken branch flow, or
-confusing ownership.
+Multiple Codex agents worked on the same files at the same time.
+They started overwriting or deleting each other's changes.
+Progress became **de-progressive**: more activity, less real forward movement.
 
-`GuardeX` adds strict guardrails so parallel agent work stays safe and predictable.
+GuardeX exists to stop that loop.
 
 ![Multi-agent dashboard example](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/dashboard-multi-agent.png)
 
-The dashboard above is the exact kind of parallel workflow GuardeX is built for.
-
-It also includes an OpenSpec planning scaffold script so plan-mode workspaces
-can be bootstrapped consistently across repos.
-
-## Install
-
-```sh
-npm i -g @imdeadpool/guardex
+```mermaid
+flowchart LR
+    A[Agent A edits file X] --> C[Conflict / overwrite]
+    B[Agent B edits file X] --> C
+    C --> D[Deleted or lost code]
+    D --> E[Rework and confusion]
+    E --> C
 ```
 
-Package page: https://www.npmjs.com/package/@imdeadpool/guardex
-
-
-## Command aliases
-
-- Preferred short command: `gx`
-- Full command: `guardex`
-- Legacy aliases still supported: `musafety`, `multiagent-safety`
+## What GuardeX enforces
 
-## Security + maintenance posture
+- isolated `agent/*` branch + worktree per task
+- explicit file lock claiming before edits
+- deletion guard for claimed files
+- protected-base branch safety (`main`, `dev`, `master` by default)
+- repair/doctor flow when drift appears
 
-- CI matrix on Node 18/20/22 (`npm test`, `node --check`, `npm pack --dry-run`)
-- trusted publishing workflow uses `npm publish --provenance` in GitHub Actions
-- OpenSSF Scorecard workflow and weekly Dependabot for GitHub Actions
-- Dedicated security disclosure policy in [`SECURITY.md`](./SECURITY.md)
-
-Related tools:
-
-- [oh-my-codex (OMX)](https://github.com/Yeachan-Heo/oh-my-codex)
-- [OpenSpec](https://github.com/Fission-AI/OpenSpec)
-- [codex-account-switcher-cli](https://github.com/recodeecom/codex-account-switcher-cli)
-
-## Fast setup (recommended)
+## Copy-paste: install + bootstrap
 
 ```sh
-# inside your repo
+npm i -g @imdeadpool/guardex
+cd /path/to/your/repo
 gx setup
-# alias:
-gx init
 ```
 
-That one command runs:
-
-1. detects whether OMX/OpenSpec/codex-auth are already globally installed,
-2. asks strict Y/N approval only if something is missing,
-3. installs guardrail scripts/hooks,
-4. repairs common safety problems,
-5. installs local Codex + Claude gx helper skill files if missing,
-6. scans and reports final status.
+Alias support:
 
-## Setup behavior screenshot
+- preferred: `gx`
+- full: `guardex`
 
-![gx status/setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
+## Copy-paste: daily workflow (per new user task)
 
-## Status logs screenshot
+```sh
+# 1) Start isolated branch/worktree
+bash scripts/agent-branch-start.sh "task-name" "agent-name"
 
-![gx service status screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/guardex-service-status.svg)
+# 2) Claim ownership
+python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
 
-## AI helper skills installed by setup/doctor
+# 3) Implement + verify
+npm test
 
-`gx setup` and `gx doctor` also ensure these local helper files exist:
+# 4) Finish (commit/push/PR/merge flow)
+bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
 
-- Codex skill: `.codex/skills/guardex/SKILL.md`
-- Claude command: `.claude/commands/guardex.md` (use as `/guardex`)
+# 5) Optional cleanup after merge
+gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
+```
 
-## Scorecard report generation
+If you use `scripts/codex-agent.sh`, the finish flow is auto-run after the Codex session exits.
 
-Create/update markdown reports from OpenSSF Scorecard JSON:
+## Visual workflow
 
-```sh
-gx report scorecard --repo github.com/recodeecom/multiagent-safety
-```
+### Setup status
 
-By default this writes:
+![gx setup behavior screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/setup-success.svg)
 
-- `docs/reports/openssf-scorecard-baseline-YYYY-MM-DD.md`
-- `docs/reports/openssf-scorecard-remediation-plan-YYYY-MM-DD.md`
+### Service logs/status
 
-## Workflow protocol screenshots
+![gx status logs screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/status-tools-logs.svg)
 
-### 1) Start isolated agent branch/worktree
+### Branch/worktree start protocol
 
 ![gx branch start protocol screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-branch-start.svg)
 
-### 2) Lock claim + deletion guard protocol
+### Lock + delete guard protocol
 
 ![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-lock-guard.svg)
 
-### 3) Multi-agent branch visibility (IDE/source control style)
-
-![gx source control multi-agent screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/workflow-source-control.svg)
-
-#### Real VS Code Source Control example (after `gx setup`)
+## Copy-paste: common commands
 
-![GuardeX real VS Code Source Control layout](./docs/images/workflow-vscode-guardex-real.png)
-
-This is the exact layout you should expect in VS Code Source Control after setup
-and a few `agent-branch-start` runs:
-
-```text
-GuardeX (your preferred local branch: main/dev)
-agent_codex_<timestamp>-<snapshot>-<task>
-agent_bot_<timestamp>-<snapshot>-<task>
-agent_bot_<timestamp>-<snapshot>-<task>
-```
-
-That gives you one stable main repo view plus parallel agent worktrees in the
-same VS Code window, so branch ownership and progress stay visible at once.
-
-## Companion tool: `codex-auth` account switcher
-
-If you run multiple Codex identities, this workflow pairs well with
-[`codex-auth`](https://github.com/recodeecom/codex-account-switcher-cli/tree/main),
-a CLI that snapshots `~/.codex/auth.json` per account and lets you switch fast
-without repeated login/logout loops.
+```sh
+# health / safety status
+gx status
 
-> [!WARNING]
-> Not affiliated with OpenAI or Codex. Not an official tool.
+# setup and repair
+gx setup
+gx doctor
 
-How `codex-auth` works:
+# protected branch management
+gx protect list
+gx protect add release staging
+gx protect remove release
 
-- stores named snapshots in `~/.codex/accounts/*.json`
-- switches by replacing active `~/.codex/auth.json`
-- keeps lightweight per-terminal session memory (default key is shell PPID),
-  so older terminals can keep their original account context
+# sync with base branch
+gx sync --check
+gx sync
 
-Requirements: Node.js 18+
+# continuously monitor open PRs targeting current branch and dispatch codex-agent review/merge tasks
+bash scripts/review-bot-watch.sh --interval 30
 
-Install:
+# cleanup merged agent branches/worktrees
+gx cleanup
 
-```sh
-npm i -g @imdeadpool/codex-account-switcher
+# scan/report
+gx scan
+gx report scorecard --repo github.com/recodeecom/multiagent-safety
 ```
 
-Common commands:
+### Continuous Codex PR monitor (local codex-auth session)
 
-```sh
-codex-auth login [name]
-codex-auth save <name>
-codex-auth use <name>
-codex-auth list --details
-codex-auth current
-codex-auth status
-codex-auth self-update --check
-```
-
-Optional shell-hook helpers:
+Run this in your local shell to keep watching PRs targeting the current branch (or `--base <branch>`):
 
 ```sh
-codex-auth setup-login-hook
-codex-auth hook-status
-codex-auth remove-login-hook
+bash scripts/review-bot-watch.sh --interval 30
 ```
 
-## Copy prompt for your AI (Codex / Claude)
+Useful flags:
 
-```sh
-gx copy-prompt
-```
+- `--base main` watch a specific base branch
+- `--only-pr 123` process only one PR
+- `--once` run one polling cycle and exit
+- `--retry-failed` retry failed PRs without waiting for a new head SHA
 
-This prints a ready-to-paste prompt.
+Note: the monitor dispatches Codex through explicit `--task/--agent/--base` flags for compatibility with both older and newer `scripts/codex-agent.sh` argument parsing.
 
-### Prompt preview (SVG)
+## Important behavior defaults
 
-![gx copy prompt screenshot](https://raw.githubusercontent.com/recodeecom/multiagent-safety/main/docs/images/copy-prompt-output.svg)
+- No command defaults to `gx status`.
+- `gx init` is alias of `gx setup`.
+- Setup/doctor can install missing global OMX/OpenSpec/codex-auth with explicit Y/N confirmation.
+- `gx setup` checks GitHub CLI (`gh`) and prints install guidance if missing.
+- Interactive self-update prompt defaults to **No** (`[y/N]`).
+- In initialized repos, `setup`/`install`/`fix` block protected-base writes unless explicitly overridden.
+- In VS Code Source Control, manual (non-Codex) commits/pushes to protected branches are allowed by default.
+- Codex/agent sessions stay blocked on protected branches and must use `agent/*` branch + PR workflow.
+- On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree.
+- `scripts/agent-branch-start.sh` hydrates `scripts/codex-agent.sh` into new sandbox worktrees when missing, so auto-finish launcher flow stays available.
 
-### Commands-only copy mode
+## Configure protected branches
 
-If you only want executable commands (without explanatory text):
+Default protected branches:
 
-```sh
-gx copy-commands
-```
-
-Example output:
+- `dev`
+- `main`
+- `master`
 
 ```sh
-npm i -g @imdeadpool/guardex
-gx setup
-gx doctor
-bash scripts/codex-agent.sh "task" "agent-name"
-bash scripts/agent-branch-start.sh "task" "agent-name"
-python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
-bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
-bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
-gx protect add release staging
-gx sync --check
-gx sync
+gx protect list
+gx protect set main release hotfix
+gx protect reset
 ```
 
-Full checklist output:
+Stored in git config key:
 
 ```text
-Use this exact checklist to setup multi-agent safety in this repository for Codex or Claude.
-
-1) Install (if missing):
-   npm i -g @imdeadpool/guardex
-
-2) Bootstrap safety in this repo:
-   gx setup
-   # alias: gx init
-
-   - Setup detects global OMX/OpenSpec/codex-auth first.
-   - If one is missing and setup asks for approval, reply explicitly:
-     - y = run: npm i -g oh-my-codex @fission-ai/openspec @imdeadpool/codex-account-switcher (missing ones only)
-     - n = skip global installs
-
-3) If setup reports warnings/errors, repair + re-check:
-   gx doctor
-
-4) Confirm next safe agent workflow commands:
-   bash scripts/codex-agent.sh "task" "agent-name"
-   bash scripts/agent-branch-start.sh "task" "agent-name"
-   python3 scripts/agent-file-locks.py claim --branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
-   bash scripts/agent-branch-finish.sh --branch "$(git rev-parse --abbrev-ref HEAD)"
-   - For every new user message/task, repeat the same cycle:
-     start isolated agent branch/worktree -> claim file locks -> implement/verify ->
-     finish via PR/merge cleanup with scripts/agent-branch-finish.sh.
-   - `scripts/codex-agent.sh` now auto-runs this finish flow after Codex exits:
-     auto-commit changed files -> push/create PR -> merge attempt -> keep branch/worktree for follow-up.
-   - Remove merged branches when you are done reviewing:
-     gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
-
-5) Optional: create OpenSpec planning workspace:
-   bash scripts/openspec/init-plan-workspace.sh "<plan-slug>"
-
-6) Optional: protect extra branches:
-   gx protect add release staging
-
-7) Optional: sync your current agent branch with latest base branch:
-   gx sync --check
-   gx sync
-
-8) Optional (GitHub remote cleanup): enable:
-   Settings -> General -> Pull Requests -> Automatically delete head branches
-```
-
-## Basic commands
-
-```sh
-gx status [--target <path>] [--json]
-gx setup [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
-gx init [--target <path>] [--dry-run] [--yes-global-install|--no-global-install] [--no-gitignore] [--allow-protected-base-write]
-gx doctor [--target <path>] [--dry-run] [--json] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
-gx copy-prompt
-gx copy-commands
-gx protect list [--target <path>]
-gx protect add <branch...> [--target <path>]
-gx protect remove <branch...> [--target <path>]
-gx protect set <branch...> [--target <path>]
-gx protect reset [--target <path>]
-gx sync --check [--target <path>] [--base <branch>] [--json]
-gx sync [--target <path>] [--base <branch>] [--strategy rebase|merge] [--ff-only]
-gx cleanup [--target <path>] [--base <branch>] [--branch <agent/...>] [--dry-run] [--force-dirty] [--keep-remote]
-gx report scorecard [--target <path>] [--repo github.com/<owner>/<repo>] [--scorecard-json <file>] [--output-dir <path>] [--date YYYY-MM-DD]
-bash scripts/agent-worktree-prune.sh   # prune temporary worktrees only (keeps merged agent branches by default)
-bash scripts/agent-worktree-prune.sh --delete-branches --delete-remote-branches   # full merged-branch cleanup
-bash scripts/agent-worktree-prune.sh --force-dirty --delete-branches   # force-remove dirty merged worktrees too
-bash scripts/openspec/init-plan-workspace.sh <plan-slug>   # optional OpenSpec plan scaffold
+multiagent.protectedBranches
 ```
 
-No command defaults to `gx status` (non-mutating health/status view).
-`gx status` reports CLI/runtime info, global OMX/OpenSpec/codex-auth service status, and repo safety service state.
-`gx init` is an alias of `gx setup`.
-When run in an interactive terminal, default `GuardeX` checks npm for a newer version first
-and asks `[y/N]` whether to update immediately (default is `N`).
-
-- Interactive setup: prompts for Y/N approval before global OMX/OpenSpec/codex-auth install.
-- Interactive prompt is strict (`[y/n]`) and waits for explicit answer.
-- Non-interactive setup: skips global installs by default; use `--yes-global-install` to force.
-- In already-initialized repos, `setup` / `install` / `fix` block writes on protected `main` by default; start an agent branch first. Use `--allow-protected-base-write` only for emergency in-place maintenance.
-- `gx doctor` on protected `main` auto-starts an isolated `agent/gx/...-gx-doctor` worktree branch and applies repairs there.
-- `gx setup` and `gx doctor` always refresh `.githooks/pre-commit` from templates, so Codex sub-branch enforcement stays repaired.
-- `scripts/codex-agent.sh` now auto-runs finish automation after a Codex session when `origin` exists:
-  auto-commit changed files, run PR/merge automation, and keep merged agent branches/worktrees by default.
-  It also auto-syncs each sandbox branch against the latest base branch before task execution.
-  If conflicts remain, it keeps the sandbox and prompts for a conflict-resolution review pass.
-- use `gx cleanup` (or `gx cleanup --branch <agent/...>`) to remove merged branches/worktrees when done.
-
-## Advanced commands
-
-```sh
-gx install [--target <path>] [--force] [--skip-agents] [--skip-package-json] [--no-gitignore] [--dry-run] [--allow-protected-base-write]
-gx fix [--target <path>] [--dry-run] [--keep-stale-locks] [--no-gitignore] [--allow-protected-base-write]
-gx scan [--target <path>] [--json]
-gx report help
-```
+## Companion dependency: GitHub CLI (`gh`)
 
-## Keep agent branches synced with your base branch
+GuardeX PR/merge automation depends on GitHub CLI (`gh`), including
+`agent-branch-finish.sh` PR flows and `codex-agent.sh` auto-finish behavior.
 
-Use sync checks before finishing agent branches:
+Install + verify:
 
 ```sh
-gx sync --check
-gx sync
+# install guide: https://cli.github.com/
+gh --version
+gh auth status
 ```
 
-Defaults:
-
-- `gx sync` base branch: `dev` (or `multiagent.baseBranch`)
-- strategy: `rebase` (or `multiagent.sync.strategy`)
-
-`agent-branch-start.sh` and `agent-branch-finish.sh` resolve base branch in this order:
-
-1. explicit `--base`
-2. `multiagent.baseBranch`
-3. branch-linked base metadata / source upstream / current checked-out branch (context-dependent)
-4. fallback `dev`
-
-Useful variants:
-
-```sh
-gx sync --strategy merge
-gx sync --all-agent-branches --check
-```
+## Companion dependency: `codex-auth` account switcher
 
-By default, `agent-branch-finish.sh` also blocks finishing when your branch is behind `origin/<base>` and points to `gx sync`.
+For multi-identity Codex workflows, GuardeX pairs with
+[`codex-auth`](https://github.com/recodeecom/codex-account-switcher-cli).
 
-Optional pre-commit behind-threshold gate (off by default):
+Install:
 
 ```sh
-git config multiagent.sync.requireBeforeCommit true
-git config multiagent.sync.maxBehindCommits 0
+npm i -g @imdeadpool/codex-account-switcher
 ```
 
-With that enabled, agent-branch commits are blocked if the branch is behind `origin/<base>` by more than the configured threshold.
-
-## Configure protected branches
-
-Default protected branches are:
-
-- `dev`
-- `main`
-- `master`
-
-You can manage additional protected branches via CLI:
+Common commands:
 
 ```sh
-gx protect list
-gx protect add release staging
-gx protect remove dev
-gx protect set main release hotfix
-gx protect reset
-```
-
-Configuration is stored in local git config key:
-
-```text
-multiagent.protectedBranches
+codex-auth save <name>
+codex-auth use <name>
+codex-auth list --details
+codex-auth current
 ```
 
-## What is protected
-
-- direct commits to protected branches (defaults: `dev`, `main`, `master`; configurable via `gx protect ...`)
-- protected-branch commits are blocked by default for all clients; Codex sessions only may commit protected branches when staged files are strictly `AGENTS.md` and/or `.gitignore`
-- Codex-session commits on non-`agent/*` branches are blocked by default (`multiagent.codexRequireAgentBranch=true`)
-- Codex commits attempted on protected branches trigger `guardex-preedit-guard` and require starting work via `scripts/codex-agent.sh`
-- overlapping file ownership between agents
-- unapproved deletions of claimed files
-- risky stale/missing lock state
-- accidental loss of critical guardrail files
-- in-place branch bootstrap requires explicit opt-in (`--in-place --allow-in-place`)
-- setup also writes a managed `.gitignore` block so generated gx scripts/hooks stay out of normal git status noise by default
-  - includes `oh-my-codex/` by default to keep local OMX source clones out of repo status
-  - pass `--no-gitignore` if you want to keep tracking these files in git
-
-## Files it installs
+## Files installed by setup
 
 ```text
 scripts/agent-branch-start.sh
 scripts/agent-branch-finish.sh
 scripts/codex-agent.sh
+scripts/review-bot-watch.sh
 scripts/agent-worktree-prune.sh
 scripts/agent-file-locks.py
 scripts/install-agent-git-hooks.sh
 scripts/openspec/init-plan-workspace.sh
 .githooks/pre-commit
+.githooks/pre-push
 .codex/skills/guardex/SKILL.md
 .claude/commands/guardex.md
 .omx/state/agent-file-locks.json
 ```
 
-If `package.json` exists, it also adds helper scripts (`agent:*`).
+If `package.json` exists, setup also adds `agent:*` helper scripts.
+
+## Security and maintenance posture
+
+- CI matrix on Node 18/20/22 (`npm test`, `node --check`, `npm pack --dry-run`)
+- trusted publishing with provenance in GitHub Actions
+- OpenSSF Scorecard + Dependabot for Actions
+- disclosure policy in [`SECURITY.md`](./SECURITY.md)
 
 ## Local development
 
@@ -414,6 +238,28 @@ npm pack --dry-run
 
 ## Release notes
 
+### v5.0.4
+
+- Bumped package version from `5.0.3` to `5.0.4` to stay one patch ahead of the current npm published version.
+
+### v5.0.3
+
+- Bumped package version from `5.0.2` to `5.0.3` for the next npm publish.
+
+### v5.0.2
+
+- Auto-closes Codex sandbox branches through PR workflow and keeps merged branch/worktree sandboxes for explicit cleanup via `gx cleanup`.
+- Runs `gx doctor` repairs from a sandbox when `main` is protected.
+- Allows tightly guarded Codex-only commits for `AGENTS.md` / `.gitignore` on protected branches.
+- Advanced package version to keep npm publishing unblocked.
+
+### v5.0.0
+
+- Rebranded the CLI to **GuardeX** with `gx`-first command UX.
+- Published under scoped package name `@imdeadpool/guardex` to avoid npm name collisions.
+- Enforced a repeatable per-message agent branch lifecycle in setup/init flows.
+- Added codex-auth-aware sandbox branch naming support.
+
 ### v0.4.6
 
 - Added repository metadata (`repository`, `bugs`, `homepage`, `funding`) in package manifest.
@@ -437,9 +283,9 @@ npm pack --dry-run
 
 - Setup now detects existing global OMX/OpenSpec installs first.
 - If tools are already present, setup skips global install automatically.
-- Interactive approval is now strict `[y/n]` (waits for explicit answer).
+- Interactive approval is strict `[y/n]` (waits for explicit answer).
 - Added setup screenshot to README.
-- Added 3 additional workflow screenshots (branch start, lock/delete guard, source-control view).
+- Added workflow screenshots (branch start, lock/delete guard, source-control view).
 
 ### v0.4.0