@imdeadpool/guardex 7.0.7 → 7.0.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +288 -371
- package/SECURITY.md +1 -1
- package/bin/multiagent-safety.js +48 -29
- package/package.json +6 -4
- package/templates/AGENTS.multiagent-safety.md +8 -8
- package/templates/claude/commands/gitguardex.md +5 -0
- package/templates/codex/skills/gitguardex/SKILL.md +11 -0
- package/templates/scripts/openspec/init-change-workspace.sh +2 -2
- package/templates/scripts/openspec/init-plan-workspace.sh +2 -2
- package/templates/claude/commands/guardex.md +0 -12
- package/templates/codex/skills/guardex/SKILL.md +0 -43
package/README.md
CHANGED
|
@@ -1,28 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# GitGuardex — Guardian T-Rex for your repo
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@imdeadpool/guardex)
|
|
4
|
-
[](https://github.com/recodeee/gitguardex/actions/workflows/ci.yml)
|
|
5
|
+
[](https://securityscorecards.dev/viewer/?uri=github.com/recodeee/gitguardex)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
**GitGuardex is a safety layer for parallel agent work in git repos.** If you're running more than one Codex or Claude agent on the same codebase, this is what keeps them from deleting each other's work.
|
|
8
8
|
|
|
9
9
|
> [!WARNING]
|
|
10
|
-
> Not affiliated with OpenAI or Codex. Not an official tool.
|
|
10
|
+
> Not affiliated with OpenAI, Anthropic, or Codex. Not an official tool.
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
---
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
- This repository tracks/mirrors the frontend under `frontend/` as documented below.
|
|
14
|
+
## The problem
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
I was running ~30 Codex agents in parallel and hit a wall: they kept working on the same files at the same time — especially tests — and started overwriting or deleting each other's changes. More agents meant *less* forward progress, not more. Classic de-progressive loop.
|
|
18
17
|
|
|
19
|
-
|
|
20
|
-
They started overwriting or deleting each other's changes.
|
|
21
|
-
Progress became **de-progressive**: more activity, less real forward movement.
|
|
18
|
+
GitGuardex exists to stop that loop. Every agent gets its own worktree, claims the files it's touching, and can't clobber files another agent has claimed. Your local branch stays clean; agents stay in their lanes.
|
|
22
19
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
20
|
+
|
|
26
21
|
|
|
27
22
|
```mermaid
|
|
28
23
|
flowchart LR
|
|
@@ -38,15 +33,21 @@ flowchart LR
|
|
|
38
33
|
I --> F
|
|
39
34
|
```
|
|
40
35
|
|
|
41
|
-
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## What it does
|
|
39
|
+
|
|
40
|
+
- **Isolated `agent/*` branch + worktree per task** — agents never share a working directory.
|
|
41
|
+
- **Explicit file lock claiming** — an agent declares which files it's editing before it edits them.
|
|
42
|
+
- **Deletion guard** — claimed files can't be removed by another agent.
|
|
43
|
+
- **Protected-base safety** — `main`, `dev`, `master` are blocked by default; agents must go through PRs.
|
|
44
|
+
- **Auto-merges agent configs into every worktree** — `oh-my-codex`, `oh-my-claude`, caveman mode, and OpenSpec all get applied automatically so every spawned agent starts tuned, not bare.
|
|
45
|
+
- **Repair/doctor flow** — when drift happens (and it will), `gx doctor` gets you back to a clean state.
|
|
46
|
+
- **Auto-finish** — when Codex exits a session, Guardex commits sandbox changes, syncs against the base, retries once if the base moved, and opens a PR.
|
|
42
47
|
|
|
43
|
-
|
|
44
|
-
- explicit file lock claiming before edits
|
|
45
|
-
- deletion guard for claimed files
|
|
46
|
-
- protected-base branch safety (`main`, `dev`, `master` by default)
|
|
47
|
-
- repair/doctor flow when drift appears
|
|
48
|
+
---
|
|
48
49
|
|
|
49
|
-
##
|
|
50
|
+
## Quick start
|
|
50
51
|
|
|
51
52
|
```sh
|
|
52
53
|
npm i -g @imdeadpool/guardex
|
|
@@ -54,292 +55,269 @@ cd /path/to/your/repo
|
|
|
54
55
|
gx setup
|
|
55
56
|
```
|
|
56
57
|
|
|
57
|
-
|
|
58
|
+
That's it. Setup installs hooks, scripts, templates, and scaffolds OpenSpec/caveman/OMX wiring. Aliases: `gx` (preferred), `gitguardex` (full), `guardex` (legacy).
|
|
58
59
|
|
|
59
|
-
|
|
60
|
-
- full: `guardex`
|
|
60
|
+
---
|
|
61
61
|
|
|
62
|
-
##
|
|
62
|
+
## Daily workflow
|
|
63
|
+
|
|
64
|
+
Per new agent task:
|
|
63
65
|
|
|
64
66
|
```sh
|
|
65
67
|
# 1) Start isolated branch/worktree
|
|
66
68
|
bash scripts/agent-branch-start.sh "task-name" "agent-name"
|
|
67
69
|
|
|
68
|
-
# 2) Claim
|
|
69
|
-
python3 scripts/agent-file-locks.py claim
|
|
70
|
+
# 2) Claim the files you're going to touch
|
|
71
|
+
python3 scripts/agent-file-locks.py claim \
|
|
72
|
+
--branch "$(git rev-parse --abbrev-ref HEAD)" <file...>
|
|
70
73
|
|
|
71
74
|
# 3) Implement + verify
|
|
72
75
|
npm test
|
|
73
76
|
|
|
74
|
-
# 4) Finish (commit
|
|
75
|
-
bash scripts/agent-branch-finish.sh
|
|
77
|
+
# 4) Finish (commit + push + PR + merge)
|
|
78
|
+
bash scripts/agent-branch-finish.sh \
|
|
79
|
+
--branch "$(git rev-parse --abbrev-ref HEAD)" \
|
|
80
|
+
--base dev --via-pr --wait-for-merge
|
|
76
81
|
|
|
77
|
-
# 5) Optional cleanup after merge
|
|
82
|
+
# 5) Optional: cleanup after merge
|
|
78
83
|
gx cleanup --branch "$(git rev-parse --abbrev-ref HEAD)"
|
|
79
84
|
```
|
|
80
85
|
|
|
81
|
-
If you use `scripts/codex-agent.sh`, the finish flow
|
|
82
|
-
It auto-commits sandbox changes, retries once after syncing if the branch moved behind base during the run, then pushes/opens PR merge flow against `dev`.
|
|
86
|
+
If you use `scripts/codex-agent.sh`, the finish flow runs automatically when the Codex session exits — it auto-commits, retries once after syncing if the base moved during the run, then pushes and opens the PR.
|
|
83
87
|
|
|
84
|
-
|
|
88
|
+
Running Codex across several existing worktrees (e.g. from VS Code Source Control)? Finalize everything ready at once:
|
|
85
89
|
|
|
86
90
|
```sh
|
|
87
91
|
gx finish --all
|
|
88
92
|
```
|
|
89
93
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
### Setup status
|
|
93
|
-
|
|
94
|
-
|
|
94
|
+
---
|
|
95
95
|
|
|
96
|
-
|
|
96
|
+
## Visual reference
|
|
97
97
|
|
|
98
|
-
|
|
98
|
+
| | |
|
|
99
|
+
|---|---|
|
|
100
|
+
|  | **`gx setup`** — bootstraps everything in one command |
|
|
101
|
+
|  | **`gx status`** — health check for tools, hooks, services |
|
|
102
|
+
|  | **Branch/worktree start protocol** |
|
|
103
|
+
|  | **Lock + delete-guard protocol** |
|
|
104
|
+
|  | **VS Code Source Control view** with agent + OpenSpec files |
|
|
99
105
|
|
|
100
|
-
###
|
|
106
|
+
### How It Works In VS Code
|
|
101
107
|
|
|
102
|
-
|
|
108
|
+
This is the real Source Control shape Guardex is aiming for: isolated agent branches, clear OpenSpec artifacts, and no pile-up on one shared checkout.
|
|
103
109
|
|
|
104
|
-
|
|
110
|
+
|
|
105
111
|
|
|
106
|
-
|
|
112
|
+
---
|
|
107
113
|
|
|
108
|
-
|
|
114
|
+
## Commands
|
|
109
115
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
## Copy-paste: common commands
|
|
116
|
+
### Core
|
|
113
117
|
|
|
114
118
|
```sh
|
|
115
|
-
# health check (default
|
|
116
|
-
gx status
|
|
117
|
-
gx
|
|
118
|
-
|
|
119
|
-
#
|
|
120
|
-
gx setup
|
|
121
|
-
gx setup --repair # repair only (v6 name: gx fix)
|
|
122
|
-
gx setup --install-only # scaffold templates, skip global installs (v6 name: gx install)
|
|
119
|
+
gx status # health check (default)
|
|
120
|
+
gx status --strict # exit non-zero on findings
|
|
121
|
+
gx setup # full bootstrap
|
|
122
|
+
gx setup --repair # repair only
|
|
123
|
+
gx setup --install-only # scaffold templates, skip global installs
|
|
123
124
|
gx doctor # repair + verify (auto-sandboxes on protected main)
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
### Targeting other repos
|
|
124
128
|
|
|
125
|
-
|
|
129
|
+
```sh
|
|
126
130
|
gx setup --target /path/to/repo
|
|
127
131
|
gx doctor --target /path/to/repo
|
|
128
|
-
|
|
132
|
+
|
|
133
|
+
# optional: VS Code workspace showing repo + agent worktrees
|
|
129
134
|
gx setup --target /path/to/repo --parent-workspace-view
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Monorepo support
|
|
138
|
+
|
|
139
|
+
Setup auto-installs into every nested git repo (e.g. `apps/*/.git`). Submodules and worktrees under `.omx/agent-worktrees/` are skipped.
|
|
130
140
|
|
|
131
|
-
|
|
132
|
-
# setup auto-installs into every nested repo; use --no-recursive to limit to the top-level
|
|
141
|
+
```sh
|
|
133
142
|
gx setup --target /mainfolder
|
|
134
143
|
gx setup --target /mainfolder --no-recursive
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Protected branches
|
|
135
147
|
|
|
136
|
-
|
|
148
|
+
```sh
|
|
137
149
|
gx protect list
|
|
138
150
|
gx protect add release staging
|
|
139
151
|
gx protect remove release
|
|
152
|
+
gx protect set main release hotfix
|
|
153
|
+
gx protect reset
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Defaults: `dev`, `main`, `master`. Stored in git config key `multiagent.protectedBranches`.
|
|
140
157
|
|
|
141
|
-
|
|
158
|
+
### Sync current agent branch
|
|
159
|
+
|
|
160
|
+
```sh
|
|
142
161
|
gx sync --check
|
|
143
162
|
gx sync
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Background bots
|
|
144
166
|
|
|
145
|
-
|
|
146
|
-
gx agents start
|
|
167
|
+
```sh
|
|
168
|
+
gx agents start # review monitor + stale cleanup
|
|
147
169
|
gx agents stop
|
|
148
170
|
gx agents status
|
|
149
171
|
|
|
150
|
-
#
|
|
151
|
-
gx
|
|
152
|
-
gx cleanup # prune merged/stale branches and worktrees
|
|
153
|
-
gx cleanup --watch --interval 60
|
|
154
|
-
|
|
155
|
-
# AI-ready setup prompt (paste into Codex/Claude)
|
|
156
|
-
gx prompt # full checklist (v6 name: gx copy-prompt)
|
|
157
|
-
gx prompt --exec # commands only (v6 name: gx copy-commands)
|
|
158
|
-
gx prompt --snippet # AGENTS.md managed block template
|
|
159
|
-
|
|
160
|
-
# reports
|
|
161
|
-
gx report scorecard --repo github.com/recodeee/guardex
|
|
172
|
+
# tuning
|
|
173
|
+
gx agents start --review-interval 30 --cleanup-interval 60 --idle-minutes 10
|
|
162
174
|
```
|
|
163
175
|
|
|
164
|
-
###
|
|
165
|
-
|
|
166
|
-
Five commands were consolidated into flags. Old names still work and print a one-line deprecation notice; they'll be removed in v8.
|
|
167
|
-
|
|
168
|
-
| v6 command | v7 replacement |
|
|
169
|
-
| ---------------------- | ------------------------ |
|
|
170
|
-
| `gx init` | `gx setup` |
|
|
171
|
-
| `gx install` | `gx setup --install-only`|
|
|
172
|
-
| `gx fix` | `gx setup --repair` |
|
|
173
|
-
| `gx scan` | `gx status --strict` |
|
|
174
|
-
| `gx copy-prompt` | `gx prompt` |
|
|
175
|
-
| `gx copy-commands` | `gx prompt --exec` |
|
|
176
|
-
| `gx print-agents-snippet` | `gx prompt --snippet` |
|
|
177
|
-
| `gx review` | `gx agents start` (runs review + cleanup) |
|
|
178
|
-
|
|
179
|
-
### Continuous stale branch cleanup bot
|
|
180
|
-
|
|
181
|
-
Use this to auto-prune idle `agent/*` worktrees created by Codex while keeping active worktrees untouched.
|
|
176
|
+
### Lifecycle
|
|
182
177
|
|
|
183
178
|
```sh
|
|
184
|
-
|
|
179
|
+
gx finish --all # commit + PR + merge every ready agent/* branch
|
|
180
|
+
gx cleanup # prune merged/stale branches and worktrees
|
|
185
181
|
gx cleanup --watch --interval 60
|
|
186
|
-
|
|
187
|
-
# one-shot cleanup for branches idle at least 10 minutes
|
|
188
182
|
gx cleanup --idle-minutes 10
|
|
189
|
-
|
|
190
|
-
# run a single watch cycle (helpful for cron/CI checks)
|
|
191
183
|
gx cleanup --watch --once --interval 60
|
|
192
184
|
```
|
|
193
185
|
|
|
194
|
-
###
|
|
186
|
+
### Prompts for your agents
|
|
195
187
|
|
|
196
188
|
```sh
|
|
197
|
-
#
|
|
198
|
-
gx
|
|
199
|
-
|
|
200
|
-
# optional tuning
|
|
201
|
-
gx agents start --review-interval 30 --cleanup-interval 60 --idle-minutes 10
|
|
202
|
-
|
|
203
|
-
# show whether both bots are running for this repo
|
|
204
|
-
gx agents status
|
|
205
|
-
|
|
206
|
-
# stop both bots and clear repo-local state
|
|
207
|
-
gx agents stop
|
|
189
|
+
gx prompt # full checklist (paste into Codex/Claude)
|
|
190
|
+
gx prompt --exec # commands only
|
|
191
|
+
gx prompt --snippet # AGENTS.md managed-block template
|
|
208
192
|
```
|
|
209
193
|
|
|
210
|
-
|
|
194
|
+
### Reports
|
|
211
195
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
- `gx setup` checks GitHub CLI (`gh`) and prints install guidance if missing.
|
|
216
|
-
- Optional parent-folder VS Code Source Control view: `gx setup --target /path/to/repo --parent-workspace-view` creates `../<repo>-branches.code-workspace`.
|
|
217
|
-
- Monorepo-aware: when the target contains nested git repos (e.g. `apps/*/.git`), `gx setup` installs the workflow into every discovered repo. Git submodules (`.git` files) and guardex worktrees under `.omx/agent-worktrees/` are skipped. Opt out with `--no-recursive`; tune discovery with `--max-depth <n>`, `--skip-nested <dir>`, and `--include-submodules`.
|
|
218
|
-
- Interactive self-update prompt defaults to **No** (`[y/N]`).
|
|
219
|
-
- In initialized repos, `setup`/`install`/`fix` block protected-base writes unless explicitly overridden.
|
|
220
|
-
- Direct commits/pushes to protected branches are blocked by default.
|
|
221
|
-
- Exception: VS Code Source Control commits are allowed on protected branches that exist only locally (no upstream and no remote branch).
|
|
222
|
-
- Optional repo override for manual VS Code protected-branch writes: `git config multiagent.allowVscodeProtectedBranchWrites true`.
|
|
223
|
-
- Codex/agent sessions stay blocked on protected branches and must use `agent/*` branch + PR workflow.
|
|
224
|
-
- On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree.
|
|
225
|
-
- In-place agent branching is disabled; `scripts/agent-branch-start.sh` always creates a separate worktree to keep your visible local/base branch unchanged.
|
|
226
|
-
- Fresh sandbox branches intentionally start without any git upstream; guardex records the protected base in `branch.<name>.guardexBase`, and the first `git push -u` publishes the real upstream branch.
|
|
227
|
-
- `scripts/agent-branch-start.sh` hydrates `scripts/codex-agent.sh` into new sandbox worktrees when missing, so auto-finish launcher flow stays available.
|
|
196
|
+
```sh
|
|
197
|
+
gx report scorecard --repo github.com/recodeee/gitguardex
|
|
198
|
+
```
|
|
228
199
|
|
|
229
|
-
|
|
200
|
+
---
|
|
230
201
|
|
|
231
|
-
|
|
202
|
+
## v6 → v7 migration
|
|
232
203
|
|
|
233
|
-
|
|
234
|
-
- `main`
|
|
235
|
-
- `master`
|
|
204
|
+
Five commands were consolidated into flags. Old names still work and print a deprecation notice; they'll be removed in v8.
|
|
236
205
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
gx
|
|
240
|
-
gx
|
|
241
|
-
|
|
206
|
+
| v6 | v7 |
|
|
207
|
+
| --------------------------- | ----------------------------- |
|
|
208
|
+
| `gx init` | `gx setup` |
|
|
209
|
+
| `gx install` | `gx setup --install-only` |
|
|
210
|
+
| `gx fix` | `gx setup --repair` |
|
|
211
|
+
| `gx scan` | `gx status --strict` |
|
|
212
|
+
| `gx copy-prompt` | `gx prompt` |
|
|
213
|
+
| `gx copy-commands` | `gx prompt --exec` |
|
|
214
|
+
| `gx print-agents-snippet` | `gx prompt --snippet` |
|
|
215
|
+
| `gx review` | `gx agents start` |
|
|
242
216
|
|
|
243
|
-
|
|
217
|
+
---
|
|
244
218
|
|
|
245
|
-
|
|
246
|
-
multiagent.protectedBranches
|
|
247
|
-
```
|
|
219
|
+
## Default behavior
|
|
248
220
|
|
|
249
|
-
|
|
221
|
+
A few things worth knowing up front:
|
|
250
222
|
|
|
251
|
-
|
|
252
|
-
|
|
223
|
+
- Running `gx` with no command opens the status/health view.
|
|
224
|
+
- `gx init` is just an alias for `gx setup`.
|
|
225
|
+
- Setup/doctor can install missing global OMX, OpenSpec, and codex-auth — but only with explicit Y/N confirmation.
|
|
226
|
+
- Direct commits/pushes to protected branches are **blocked** by default. Agents must use the `agent/*` + PR flow.
|
|
227
|
+
- **Exception:** VS Code Source Control commits are allowed on protected branches that exist only locally (no upstream, no remote branch).
|
|
228
|
+
- On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree so it can't touch your real main.
|
|
229
|
+
- In-place agent branching is disabled. `scripts/agent-branch-start.sh` always creates a separate worktree so your visible local/base branch never changes.
|
|
230
|
+
- Fresh sandbox branches start with no git upstream. Guardex records the protected base in `branch.<name>.guardexBase`, and the first `git push -u` publishes the real upstream.
|
|
231
|
+
- Interactive self-update prompt defaults to **No** (`[y/N]`).
|
|
253
232
|
|
|
254
|
-
|
|
233
|
+
Optional override for manual VS Code protected-branch writes:
|
|
255
234
|
|
|
256
235
|
```sh
|
|
257
|
-
|
|
258
|
-
gh --version
|
|
259
|
-
gh auth status
|
|
236
|
+
git config multiagent.allowVscodeProtectedBranchWrites true
|
|
260
237
|
```
|
|
261
238
|
|
|
262
|
-
|
|
239
|
+
---
|
|
240
|
+
|
|
241
|
+
## Companion tools
|
|
263
242
|
|
|
264
|
-
|
|
243
|
+
GitGuardex is designed to work alongside these. All optional — but if you're running many agents, you probably want them.
|
|
265
244
|
|
|
266
|
-
|
|
245
|
+
### GitHub CLI (`gh`)
|
|
267
246
|
|
|
268
|
-
|
|
247
|
+
Required for PR/merge automation. `agent-branch-finish.sh` and `codex-agent.sh` auto-finish both depend on it.
|
|
269
248
|
|
|
270
249
|
```sh
|
|
271
|
-
|
|
250
|
+
# https://cli.github.com/
|
|
251
|
+
gh --version
|
|
252
|
+
gh auth status
|
|
272
253
|
```
|
|
273
254
|
|
|
274
|
-
|
|
255
|
+
### codex-auth — multi-account switcher
|
|
275
256
|
|
|
276
|
-
-
|
|
277
|
-
- set `rules[].upstream` to `<upstream-owner>:<branch>`
|
|
257
|
+
For multi-identity Codex workflows. I built this because switching accounts manually for 30 agents was impossible.
|
|
278
258
|
|
|
279
|
-
|
|
280
|
-
|
|
259
|
+
```sh
|
|
260
|
+
npm i -g @imdeadpool/codex-account-switcher
|
|
281
261
|
|
|
282
|
-
|
|
262
|
+
codex-auth save <name>
|
|
263
|
+
codex-auth use <name>
|
|
264
|
+
codex-auth list --details
|
|
265
|
+
codex-auth current
|
|
266
|
+
```
|
|
283
267
|
|
|
284
|
-
|
|
268
|
+
Repo: [recodeecom/codex-account-switcher-cli](https://github.com/recodeecom/codex-account-switcher-cli)
|
|
285
269
|
|
|
286
|
-
|
|
270
|
+
### Pull app — fork auto-sync
|
|
287
271
|
|
|
288
|
-
|
|
272
|
+
Guardex installs a starter config at `.github/pull.yml.example`.
|
|
289
273
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
274
|
+
```sh
|
|
275
|
+
cp .github/pull.yml.example .github/pull.yml
|
|
276
|
+
# edit rules[].base and rules[].upstream
|
|
277
|
+
```
|
|
293
278
|
|
|
294
|
-
|
|
279
|
+
Install the app: <https://github.com/apps/pull>
|
|
280
|
+
Validate: `https://pull.git.ci/check/<owner>/<repo>`
|
|
295
281
|
|
|
296
|
-
|
|
282
|
+
### CR-GPT — AI PR reviews
|
|
297
283
|
|
|
298
|
-
|
|
299
|
-
the `frontend/` subtree to a separate repository whenever `main` receives
|
|
300
|
-
changes under `frontend/**`.
|
|
284
|
+
Install: <https://github.com/apps/cr-gpt>
|
|
301
285
|
|
|
302
|
-
|
|
286
|
+
`gx setup` installs `.github/workflows/cr.yml`. Then add `OPENAI_API_KEY` under `Settings → Secrets and variables → Actions → Variables`. After that, new and updated PRs get reviewed automatically.
|
|
303
287
|
|
|
304
|
-
|
|
305
|
-
- branch: `main`
|
|
288
|
+
---
|
|
306
289
|
|
|
307
|
-
|
|
290
|
+
## OpenSpec integration
|
|
308
291
|
|
|
309
|
-
|
|
310
|
-
2. Add repository secret `GUARDEX_FRONTEND_MIRROR_PAT`
|
|
311
|
-
- value must be a token with `contents:write` access to `Webu-PRO/guardex-frontend`
|
|
292
|
+
If you installed OpenSpec during setup (`@fission-ai/openspec`), the full guide is at [`docs/openspec-getting-started.md`](./docs/openspec-getting-started.md).
|
|
312
293
|
|
|
313
|
-
|
|
294
|
+
Default flow:
|
|
314
295
|
|
|
315
|
-
|
|
316
|
-
-
|
|
296
|
+
```text
|
|
297
|
+
/opsx:propose <change-name> → /opsx:apply → /opsx:archive
|
|
298
|
+
```
|
|
317
299
|
|
|
318
|
-
|
|
300
|
+
Expanded flow:
|
|
319
301
|
|
|
320
|
-
```
|
|
321
|
-
|
|
302
|
+
```text
|
|
303
|
+
/opsx:new <change-name> → /opsx:ff or /opsx:continue → /opsx:apply → /opsx:verify → /opsx:archive
|
|
322
304
|
```
|
|
323
305
|
|
|
324
|
-
|
|
306
|
+
### OpenSpec in agent sub-branches
|
|
325
307
|
|
|
326
|
-
|
|
327
|
-
|
|
308
|
+
- `scripts/codex-agent.sh` enforces OpenSpec workspaces before launching Codex.
|
|
309
|
+
- `scripts/agent-branch-start.sh` can scaffold both `openspec/changes/<slug>/` and `openspec/plan/<slug>/` when `GUARDEX_OPENSPEC_AUTO_INIT=true`.
|
|
328
310
|
|
|
329
|
-
|
|
311
|
+
Environment variables:
|
|
330
312
|
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
313
|
+
| Var | Purpose |
|
|
314
|
+
|---|---|
|
|
315
|
+
| `GUARDEX_OPENSPEC_AUTO_INIT` | `true` to auto-bootstrap on branch start (default `false`) |
|
|
316
|
+
| `GUARDEX_OPENSPEC_PLAN_SLUG` | force a specific plan workspace name |
|
|
317
|
+
| `GUARDEX_OPENSPEC_CHANGE_SLUG` | force a specific change workspace name |
|
|
318
|
+
| `GUARDEX_OPENSPEC_CAPABILITY_SLUG` | override capability folder for `spec.md` scaffolding |
|
|
334
319
|
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
```sh
|
|
338
|
-
codex-auth save <name>
|
|
339
|
-
codex-auth use <name>
|
|
340
|
-
codex-auth list --details
|
|
341
|
-
codex-auth current
|
|
342
|
-
```
|
|
320
|
+
---
|
|
343
321
|
|
|
344
322
|
## Files installed by setup
|
|
345
323
|
|
|
@@ -354,8 +332,8 @@ scripts/install-agent-git-hooks.sh
|
|
|
354
332
|
scripts/openspec/init-plan-workspace.sh
|
|
355
333
|
.githooks/pre-commit
|
|
356
334
|
.githooks/pre-push
|
|
357
|
-
.codex/skills/
|
|
358
|
-
.claude/commands/
|
|
335
|
+
.codex/skills/gitguardex/SKILL.md
|
|
336
|
+
.claude/commands/gitguardex.md
|
|
359
337
|
.github/pull.yml.example
|
|
360
338
|
.github/workflows/cr.yml
|
|
361
339
|
.omx/state/agent-file-locks.json
|
|
@@ -363,44 +341,51 @@ scripts/openspec/init-plan-workspace.sh
|
|
|
363
341
|
|
|
364
342
|
If `package.json` exists, setup also adds `agent:*` helper scripts.
|
|
365
343
|
|
|
366
|
-
|
|
344
|
+
---
|
|
367
345
|
|
|
368
|
-
|
|
346
|
+
## Frontend mirror
|
|
369
347
|
|
|
370
|
-
-
|
|
348
|
+
- Standalone frontend repo: <https://github.com/Webu-PRO/guardex-frontend>
|
|
349
|
+
- This repo tracks the frontend under `frontend/` and auto-mirrors it via `.github/workflows/sync-frontend-mirror.yml` on changes to `main`.
|
|
371
350
|
|
|
372
|
-
|
|
351
|
+
Setup (in this repo):
|
|
373
352
|
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
353
|
+
1. `Settings → Secrets and variables → Actions`
|
|
354
|
+
2. Add secret `GUARDEX_FRONTEND_MIRROR_PAT` with `contents:write` on `Webu-PRO/guardex-frontend`
|
|
355
|
+
|
|
356
|
+
Optional overrides (Actions Variables):
|
|
377
357
|
|
|
378
|
-
|
|
358
|
+
- `GUARDEX_FRONTEND_MIRROR_REPO` (default `Webu-PRO/guardex-frontend`)
|
|
359
|
+
- `GUARDEX_FRONTEND_MIRROR_BRANCH` (default `main`)
|
|
360
|
+
|
|
361
|
+
Manual run:
|
|
379
362
|
|
|
380
363
|
```sh
|
|
381
|
-
|
|
382
|
-
openspec update
|
|
364
|
+
gh workflow run sync-frontend-mirror.yml
|
|
383
365
|
```
|
|
384
366
|
|
|
385
|
-
|
|
386
|
-
/opsx:new <change-name> -> /opsx:ff or /opsx:continue -> /opsx:apply -> /opsx:verify -> /opsx:archive
|
|
387
|
-
```
|
|
367
|
+
---
|
|
388
368
|
|
|
389
|
-
|
|
369
|
+
## Known rough edges
|
|
370
|
+
|
|
371
|
+
Being honest about where this still has issues:
|
|
372
|
+
|
|
373
|
+
- **Usage limit mid-task.** When an agent hits its Codex/Claude usage limit partway through, the cleanup flow currently has to be handed to a different agent. It works, but the handoff is uglier than I'd like.
|
|
374
|
+
- **Conflict-stuck probes.** Fixed in v7.0.2 — earlier versions could leak `__source-probe-*` worktrees when the sync-guard rebase hit conflicts. If you're on an older release, `gx cleanup` sweeps these.
|
|
375
|
+
- **Windows.** Most of the hook surface assumes a POSIX shell. Use WSL or symlink-enabled git if you're on Windows.
|
|
390
376
|
|
|
391
|
-
|
|
392
|
-
- `scripts/agent-branch-start.sh` can scaffold both `openspec/changes/<agent-branch-slug>/` and `openspec/plan/<agent-branch-slug>/` when you set `GUARDEX_OPENSPEC_AUTO_INIT=true`.
|
|
393
|
-
- Set `GUARDEX_OPENSPEC_AUTO_INIT=false` (default for `agent-branch-start`) to skip branch-start auto-bootstrap.
|
|
394
|
-
- Set `GUARDEX_OPENSPEC_PLAN_SLUG=<kebab-case-slug>` to force a specific plan workspace name.
|
|
395
|
-
- Set `GUARDEX_OPENSPEC_CHANGE_SLUG=<kebab-case-slug>` to force a specific change workspace name.
|
|
396
|
-
- Set `GUARDEX_OPENSPEC_CAPABILITY_SLUG=<kebab-case-slug>` to override the default capability folder used for `spec.md` scaffolding.
|
|
377
|
+
PRs and issues welcome.
|
|
397
378
|
|
|
398
|
-
|
|
379
|
+
---
|
|
399
380
|
|
|
400
|
-
|
|
401
|
-
|
|
381
|
+
## Security & maintenance
|
|
382
|
+
|
|
383
|
+
- CI matrix on Node 18 / 20 / 22 (`npm test`, `node --check`, `npm pack --dry-run`)
|
|
384
|
+
- Trusted publishing with provenance via GitHub Actions
|
|
402
385
|
- OpenSSF Scorecard + Dependabot for Actions
|
|
403
|
-
-
|
|
386
|
+
- Disclosure policy in [`SECURITY.md`](./SECURITY.md)
|
|
387
|
+
|
|
388
|
+
---
|
|
404
389
|
|
|
405
390
|
## Local development
|
|
406
391
|
|
|
@@ -410,201 +395,133 @@ node --check bin/multiagent-safety.js
|
|
|
410
395
|
npm pack --dry-run
|
|
411
396
|
```
|
|
412
397
|
|
|
398
|
+
---
|
|
399
|
+
|
|
413
400
|
## Release notes
|
|
414
401
|
|
|
415
|
-
|
|
402
|
+
<details>
|
|
403
|
+
<summary><strong>v7.x</strong></summary>
|
|
416
404
|
|
|
417
|
-
|
|
418
|
-
-
|
|
405
|
+
### v7.0.10
|
|
406
|
+
- Primary user-facing long name is now **GitGuardex**. CLI/help presents `gitguardex` as the long-form command; `gx` stays the preferred short alias; `guardex` remains as legacy compatibility.
|
|
407
|
+
- Installed Codex/Claude startup files now use `gitguardex` paths: `.codex/skills/gitguardex/SKILL.md` and `.claude/commands/gitguardex.md`.
|
|
408
|
+
- Startup context shrunk further. Managed marker block + skill + command compressed from 4340 B → 1930 B across the three always-loaded template files.
|
|
409
|
+
- Bumped `@imdeadpool/guardex` from `7.0.9` → `7.0.10`.
|
|
419
410
|
|
|
420
|
-
### v7.0.
|
|
411
|
+
### v7.0.9
|
|
412
|
+
- `gx doctor` and `gx setup` now refresh AGENTS with repo-toggle examples. Managed AGENTS block states Guardex is enabled by default and shows exact `.env` lines: `GUARDEX_ON=0` disables per repo, `GUARDEX_ON=1` re-enables.
|
|
413
|
+
- Bumped to `7.0.9`.
|
|
421
414
|
|
|
422
|
-
|
|
415
|
+
### v7.0.8
|
|
416
|
+
- Added `REPO TOGGLE` section to `gx` status/help output. Operators see the repo-local switch immediately.
|
|
417
|
+
- Bumped to `7.0.8`.
|
|
423
418
|
|
|
424
|
-
### v7.0.
|
|
419
|
+
### v7.0.7
|
|
420
|
+
- Advanced next publish target past npm. Bumped to `7.0.7`.
|
|
421
|
+
- Fixed root package metadata drift in `package-lock.json` (root version had fallen behind manifest).
|
|
425
422
|
|
|
426
|
-
|
|
427
|
-
- **
|
|
423
|
+
### v7.0.6
|
|
424
|
+
- **Fixed: self-updater lied about success.** `gx`'s update prompt runs `npm i -g @imdeadpool/guardex@latest` and previously trusted npm's exit code. When npm's resolution cache reported "changed 1 package" without actually overwriting files (known quirk, triggers when user just bumped N-1 → N in the same session, or with a warm metadata cache), the prompt kept re-firing on every subsequent `gx` invocation because the on-disk `package.json` was stale. `gx` now re-reads the globally installed `package.json` after `@latest` returns, compares its `version` to the advertised latest, and if they don't match runs a pinned retry `npm i -g @imdeadpool/guardex@<latest>` to force past the obstructing cache entry. If the pinned retry also fails, the user gets a clear hint (`npm root -g && npm cache verify`) instead of a silent loop.
|
|
428
425
|
|
|
429
|
-
### v7.0.
|
|
426
|
+
### v7.0.5
|
|
427
|
+
- Added `oh-my-claude` to `gx status` global-toolchain check. Claude-side mirror of `oh-my-codex` is reported alongside existing services (`oh-my-codex`, `@fission-ai/openspec`, `@imdeadpool/codex-account-switcher`, `gh`).
|
|
428
|
+
- Added `.omc/` to the managed `.gitignore` block so Claude-specific runtime state (notepad, worktrees) stays out of commits, parity with `.omx/`.
|
|
430
429
|
|
|
431
|
-
|
|
432
|
-
-
|
|
430
|
+
### v7.0.4
|
|
431
|
+
- Fixed publish collision on npm. Bumped `7.0.3` → `7.0.4`.
|
|
433
432
|
|
|
434
433
|
### v7.0.3
|
|
435
|
-
|
|
436
|
-
- **
|
|
437
|
-
-
|
|
438
|
-
-
|
|
439
|
-
- **`--tier` flag accepted silently** for CLAUDE.md compatibility (scaffold sizing not wired through yet).
|
|
440
|
-
- Tests `install.test.js` covering the old snapshot-slug format were rewritten to assert the new role-datetime shape.
|
|
434
|
+
- **Branch/worktree naming refactor.** `agent-branch-start.sh` now produces `agent/<role>/<task>-<YYYY-MM-DD>-<HH-MM>` instead of `agent/<role+account-email>/<snapshot-slug>-<task>-<cksum6>`. Account names and 6-hex checksums no longer leak into branch/worktree paths.
|
|
435
|
+
- **Role normalization.** `AGENT_NAME` collapses to `{claude, codex, <explicit>}` via (in order) `GUARDEX_AGENT_TYPE` env override, substring match against `claude`/`codex`, `CLAUDECODE=1` sentinel, or fallback to `codex`. Other roles (`integrator`, `executor`, etc.) pass through when set via `GUARDEX_AGENT_TYPE`.
|
|
436
|
+
- New `--print-name-only` flag for deterministic tests; honors `GUARDEX_BRANCH_TIMESTAMP` for reproducible output.
|
|
437
|
+
- `--tier` flag accepted silently for CLAUDE.md compatibility (scaffold sizing not wired through yet).
|
|
441
438
|
|
|
442
439
|
### v7.0.2
|
|
443
|
-
|
|
444
|
-
-
|
|
445
|
-
- The cleanup trap is now installed immediately after probe creation, and aborts any in-progress `rebase`/`merge` before `worktree remove --force` so conflict-stuck probes are cleaned up reliably.
|
|
440
|
+
- **Fix: `__source-probe-*` worktree leak on conflict exit.** `agent-branch-finish.sh` was registering its `cleanup()` trap *after* the sync-guard rebase block, so when rebase hit conflicts and the script exited, the throwaway probe worktree was never removed. `gx doctor` sweeps accumulated one new probe per run.
|
|
441
|
+
- Cleanup trap is now installed immediately after probe creation, and aborts any in-progress `rebase`/`merge` before `worktree remove --force`.
|
|
446
442
|
|
|
447
443
|
### v7.0.1
|
|
448
|
-
|
|
449
444
|
- Maintenance release.
|
|
450
445
|
|
|
451
446
|
### v7.0.0
|
|
452
|
-
|
|
453
|
-
- **
|
|
454
|
-
- **Token-usage improvements.** Trimmed the auto-installed agent templates that live inside every consumer repo and get loaded into every Claude/Codex session:
|
|
447
|
+
- **Breaking (soft).** Consolidated 17 commands into 12 visible commands with flag-based subcommands. Removed names still work but print a deprecation notice; will be removed in v8.
|
|
448
|
+
- **Token-usage improvements.** Trimmed auto-installed agent templates that live in every consumer repo and get loaded into every session:
|
|
455
449
|
- `templates/AGENTS.multiagent-safety.md`: 6990 B → 1615 B (−77%)
|
|
456
450
|
- `templates/codex/skills/guardex/SKILL.md`: 2732 B → 1086 B (−60%)
|
|
457
451
|
- `templates/claude/commands/guardex.md`: 472 B → 357 B (−24%)
|
|
458
452
|
- Total: 10194 B → 3058 B per consumer repo (−70%, ~1.5k fewer tokens per agent session).
|
|
453
|
+
- New `gx prompt` command replaces three prompt-emitting commands.
|
|
454
|
+
- New flag surface on `gx setup`: `--install-only`, `--repair`.
|
|
455
|
+
- New `gx status --strict` mirrors old `gx scan`.
|
|
459
456
|
|
|
460
|
-
|
|
461
|
-
- **New `gx prompt` command** replaces three prompt-emitting commands: `gx prompt` (full checklist), `gx prompt --exec` (commands only), `gx prompt --snippet` (AGENTS.md managed-block template).
|
|
462
|
-
- **New flag surface on `gx setup`**: `--install-only` (templates/hooks/locks only), `--repair` (fix drift), plus the existing `--target`, `--parent-workspace-view`, `--dry-run`, etc.
|
|
463
|
-
- **New `gx status --strict`** mirrors the old `gx scan` behavior (exit non-zero on findings).
|
|
464
|
-
- Updated internal `REQUIRED_PACKAGE_SCRIPTS` for consumer `package.json` so `agent:safety:scan` and `agent:safety:fix` helper scripts now invoke the new v7 surface (`gx status --strict`, `gx setup --repair`).
|
|
457
|
+
</details>
|
|
465
458
|
|
|
466
|
-
|
|
459
|
+
<details>
|
|
460
|
+
<summary><strong>v6.x</strong></summary>
|
|
467
461
|
|
|
468
|
-
|
|
469
|
-
- Preserve existing `
|
|
470
|
-
-
|
|
471
|
-
-
|
|
472
|
-
-
|
|
462
|
+
### v6.0.1
|
|
463
|
+
- Preserve existing repo-owned `AGENTS.md` marker content during `gx setup` / `gx doctor` by default; only rewrite marker blocks when `--force` is explicit.
|
|
464
|
+
- Preserve existing `agent:*` package scripts during setup/doctor repairs by default.
|
|
465
|
+
- Forward `--force` through sandboxed doctor execution.
|
|
466
|
+
- Added regression tests for both preservation behaviors.
|
|
473
467
|
|
|
474
468
|
### v6.0.0
|
|
469
|
+
- **Breaking** — removed legacy `musafety` bin alias and all `MUSAFETY_*` environment variables. Callers must migrate to `guardex` / `gx` and `GUARDEX_*`.
|
|
470
|
+
- **Breaking** — bootstrap manifest filename changed from `musafety-bootstrap-manifest.json` to `guardex-bootstrap-manifest.json`; existing sandbox worktrees must be pruned + re-bootstrapped.
|
|
471
|
+
- Rebranded `musafety` → `guardex` across scripts, templates, hooks, tests, docs.
|
|
472
|
+
- The descriptive phrase `multiagent-safety` (including `bin/multiagent-safety.js`) is preserved — only the short codename changed.
|
|
475
473
|
|
|
476
|
-
|
|
477
|
-
- **Breaking** — bootstrap manifest filename changed from `musafety-bootstrap-manifest.json` to `guardex-bootstrap-manifest.json`; existing sandbox worktrees must be pruned + re-bootstrapped (or have their manifest manually renamed).
|
|
478
|
-
- Rebranded all remaining `musafety` / `Musafety` / `MUSAFETY` codename tokens to `guardex` / `Guardex` / `GUARDEX` across scripts, templates, hooks, tests, and docs.
|
|
479
|
-
- The descriptive phrase `multiagent-safety` (including `bin/multiagent-safety.js` and `templates/AGENTS.multiagent-safety.md`) is preserved intentionally — only the short codename changed.
|
|
480
|
-
- Bumped package version from `5.0.17` to `6.0.0` for the next npm publish.
|
|
481
|
-
|
|
482
|
-
### v5.0.17
|
|
483
|
-
|
|
484
|
-
- Bumped package version from `5.0.16` to `5.0.17` for the next npm publish.
|
|
485
|
-
|
|
486
|
-
### v5.0.16
|
|
487
|
-
|
|
488
|
-
- Fixed `gx doctor` runtime crash (`parseDoctorArgs is not defined`) by restoring the doctor argument parser for `--target` and `--strict`.
|
|
489
|
-
- Fixed `gx doctor` command routing so the repair-first doctor flow remains the active command path (duplicate legacy doctor definition no longer overrides it).
|
|
490
|
-
- Updated worktree change detection to run `git status --porcelain --untracked-files=normal --` for consistent normal untracked-file behavior.
|
|
491
|
-
- Added regression coverage that asserts the doctor parser function exists in `bin/multiagent-safety.js`.
|
|
492
|
-
- Bumped package version from `5.0.15` to `5.0.16`.
|
|
493
|
-
|
|
494
|
-
### v5.0.15
|
|
495
|
-
|
|
496
|
-
- Added `gx setup --parent-workspace-view` to generate a parent-folder VS Code workspace (`../<repo>-branches.code-workspace`) that shows both the base repo and `.omx/agent-worktrees` in Source Control.
|
|
497
|
-
- Added dry-run-safe parent workspace operations (`would-create` / `would-update`) and setup output that prints the created workspace path.
|
|
498
|
-
- Added regression coverage for parent workspace generation and dry-run behavior.
|
|
499
|
-
- Bumped package version from `5.0.14` to `5.0.15`.
|
|
500
|
-
|
|
501
|
-
### v5.0.14
|
|
502
|
-
|
|
503
|
-
- Changed release metadata for the next npm publish by bumping package version from `5.0.13` to `5.0.14`.
|
|
504
|
-
- Kept Guardex release notes synchronized with the published package version.
|
|
505
|
-
|
|
506
|
-
### v5.0.13
|
|
507
|
-
|
|
508
|
-
- Bumped package version from `5.0.12` to `5.0.13` for the next npm publish.
|
|
509
|
-
|
|
510
|
-
### v5.0.12
|
|
511
|
-
|
|
512
|
-
- Bumped package version from `5.0.11` to `5.0.12` for the next npm publish.
|
|
513
|
-
- Updated repository metadata and README links to the renamed GitHub repository (`recodeee/guardex`).
|
|
514
|
-
|
|
515
|
-
### v5.0.11
|
|
516
|
-
|
|
517
|
-
- 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.
|
|
518
|
-
- Ensured `gx install` explicitly configures the managed `AGENTS.md` policy block and added regression coverage for this install-path behavior.
|
|
519
|
-
- Bumped package version from `5.0.10` to `5.0.11` for the next npm publish.
|
|
520
|
-
|
|
521
|
-
### v5.0.10
|
|
474
|
+
</details>
|
|
522
475
|
|
|
523
|
-
|
|
476
|
+
<details>
|
|
477
|
+
<summary><strong>v5.x</strong></summary>
|
|
524
478
|
|
|
525
|
-
### v5.0.
|
|
526
|
-
|
|
527
|
-
- Enforced OpenSpec workspace bootstrap for sandbox agent execution: `scripts/codex-agent.sh` now initializes `openspec/plan/<agent-branch-slug>/` before launching Codex, and `scripts/agent-branch-start.sh` supports `GUARDEX_OPENSPEC_AUTO_INIT` plus `GUARDEX_OPENSPEC_PLAN_SLUG`.
|
|
528
|
-
- Tightened doctor auto-finish correctness: sandbox finish now waits for merge and exits non-zero if the PR closes without merge, so repair flows are not reported as complete when policy blocks merge.
|
|
529
|
-
- Updated package version from `5.0.8` to `5.0.9` for the next npm publish.
|
|
530
|
-
|
|
531
|
-
### v5.0.8
|
|
532
|
-
|
|
533
|
-
- Fixed `bin/multiagent-safety.js` syntax regressions in the doctor sandbox flow (`Unexpected identifier` / `Unexpected end of input`) that were breaking CLI execution and CI tests.
|
|
534
|
-
- Restored `scripts/codex-agent.sh` from `templates/scripts/codex-agent.sh` so critical runtime helper parity checks pass in clean CI clones.
|
|
535
|
-
- Bumped package version from `5.0.7` to `5.0.8` for the next npm publish.
|
|
536
|
-
|
|
537
|
-
### v5.0.7
|
|
538
|
-
### Unreleased (generated draft, not versioned yet)
|
|
539
|
-
|
|
540
|
-
- Add the user-facing changes for the next release here before assigning a version number.
|
|
541
|
-
- Keep this section focused on behavior changes (`Added`, `Changed`, `Fixed`) rather than version-bump-only notes.
|
|
479
|
+
### v5.0.17 – v5.0.10
|
|
480
|
+
Version bumps for npm publish continuity plus incremental fixes: doctor arg-parser restored (5.0.16), parent-workspace view added (5.0.15), OMX completion policy wording (5.0.11), OpenSpec sandbox bootstrap enforced (5.0.9), bin syntax regressions fixed (5.0.8).
|
|
542
481
|
|
|
543
482
|
### v5.0.6
|
|
544
|
-
|
|
545
|
-
- `gx cleanup
|
|
546
|
-
- Added `gx cleanup --keep-clean-worktrees` to opt out and keep clean worktrees visible.
|
|
547
|
-
- Bumped package version from `5.0.5` to `5.0.6` for the next npm publish.
|
|
548
|
-
|
|
549
|
-
### v5.0.5
|
|
550
|
-
|
|
551
|
-
- Bumped package version from `5.0.4` to `5.0.5` so npm publish can proceed with the next patch release.
|
|
552
|
-
|
|
553
|
-
### v5.0.4
|
|
554
|
-
|
|
555
|
-
- Bumped package version from `5.0.3` to `5.0.4` to stay one patch ahead of the current npm published version.
|
|
556
|
-
|
|
557
|
-
### v5.0.3
|
|
558
|
-
|
|
559
|
-
- Bumped package version from `5.0.2` to `5.0.3` for the next npm publish.
|
|
483
|
+
- `gx cleanup` and auto-finish cleanup now prune clean agent worktrees by default. VS Code Source Control focuses on your local branch + worktrees with active changes.
|
|
484
|
+
- Added `gx cleanup --keep-clean-worktrees` to opt out.
|
|
560
485
|
|
|
561
486
|
### v5.0.2
|
|
562
|
-
|
|
563
|
-
- Auto-closes Codex sandbox branches through PR workflow and keeps merged branch/worktree sandboxes for explicit cleanup via `gx cleanup`.
|
|
487
|
+
- Auto-closes Codex sandbox branches through PR workflow; keeps merged branch/worktree sandboxes for explicit cleanup via `gx cleanup`.
|
|
564
488
|
- Runs `gx doctor` repairs from a sandbox when `main` is protected.
|
|
565
489
|
- Allows tightly guarded Codex-only commits for `AGENTS.md` / `.gitignore` on protected branches.
|
|
566
|
-
- Advanced package version to keep npm publishing unblocked.
|
|
567
490
|
|
|
568
491
|
### v5.0.0
|
|
569
|
-
|
|
570
|
-
-
|
|
571
|
-
-
|
|
572
|
-
- Enforced a repeatable per-message agent branch lifecycle in setup/init flows.
|
|
492
|
+
- Rebranded CLI to **GuardeX** with `gx`-first command UX.
|
|
493
|
+
- Published under scoped package name `@imdeadpool/guardex`.
|
|
494
|
+
- Enforced repeatable per-message agent branch lifecycle in setup/init flows.
|
|
573
495
|
- Added codex-auth-aware sandbox branch naming support.
|
|
574
496
|
|
|
575
|
-
|
|
497
|
+
</details>
|
|
576
498
|
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
499
|
+
<details>
|
|
500
|
+
<summary><strong>v0.4.x</strong></summary>
|
|
501
|
+
|
|
502
|
+
### v0.4.6
|
|
503
|
+
- Added repository metadata (`repository`, `bugs`, `homepage`, `funding`).
|
|
504
|
+
- Added CI workflow for Node 18/20/22.
|
|
505
|
+
- Added npm provenance release workflow, OpenSSF Scorecard, Dependabot for Actions.
|
|
580
506
|
- Added explicit `SECURITY.md` and `CONTRIBUTING.md`.
|
|
581
507
|
|
|
582
508
|
### v0.4.5
|
|
583
|
-
|
|
584
509
|
- Added optional pre-commit behind-threshold sync gate (`multiagent.sync.requireBeforeCommit`, `multiagent.sync.maxBehindCommits`).
|
|
585
|
-
- Added `gx sync` workflow (`--check`,
|
|
586
|
-
- `agent-branch-finish.sh`
|
|
510
|
+
- Added `gx sync` workflow (`--check`, strategies, report mode).
|
|
511
|
+
- `agent-branch-finish.sh` blocks finishing when source is behind `origin/<base>`.
|
|
587
512
|
|
|
588
513
|
### v0.4.4
|
|
589
|
-
|
|
590
514
|
- Added `scripts/agent-worktree-prune.sh` to templates/install.
|
|
591
|
-
- `agent-branch-finish.sh`
|
|
592
|
-
- Added npm helper
|
|
515
|
+
- `agent-branch-finish.sh` auto-runs prune after merge.
|
|
516
|
+
- Added npm helper: `agent:cleanup`.
|
|
593
517
|
|
|
594
518
|
### v0.4.2
|
|
595
|
-
|
|
596
|
-
-
|
|
597
|
-
-
|
|
598
|
-
- Interactive approval is strict `[y/n]` (waits for explicit answer).
|
|
599
|
-
- Added setup screenshot to README.
|
|
600
|
-
- Added workflow screenshots (branch start, lock/delete guard, source-control view).
|
|
519
|
+
- Setup detects existing global OMX/OpenSpec installs first; skips global install if tools are present.
|
|
520
|
+
- Interactive approval is strict `[y/n]`.
|
|
521
|
+
- Added setup + workflow screenshots.
|
|
601
522
|
|
|
602
523
|
### v0.4.0
|
|
524
|
+
- Added setup-time Y/N approval for optional global install of `oh-my-codex` and `@fission-ai/openspec`.
|
|
525
|
+
- Added setup flags: `--yes-global-install`, `--no-global-install`.
|
|
603
526
|
|
|
604
|
-
|
|
605
|
-
- `oh-my-codex`
|
|
606
|
-
- `@fission-ai/openspec`
|
|
607
|
-
- Added setup flags for automation:
|
|
608
|
-
- `--yes-global-install`
|
|
609
|
-
- `--no-global-install`
|
|
610
|
-
- Added official repo links for OMX and OpenSpec.
|
|
527
|
+
</details>
|
package/SECURITY.md
CHANGED
package/bin/multiagent-safety.js
CHANGED
|
@@ -7,7 +7,7 @@ const cp = require('node:child_process');
|
|
|
7
7
|
const packageJsonPath = path.resolve(__dirname, '..', 'package.json');
|
|
8
8
|
const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
|
|
9
9
|
|
|
10
|
-
const TOOL_NAME = '
|
|
10
|
+
const TOOL_NAME = 'gitguardex';
|
|
11
11
|
const SHORT_TOOL_NAME = 'gx';
|
|
12
12
|
const LEGACY_NAMES = ['guardex', 'multiagent-safety'];
|
|
13
13
|
const OPENSPEC_PACKAGE = '@fission-ai/openspec';
|
|
@@ -58,9 +58,9 @@ const TEMPLATE_FILES = [
|
|
|
58
58
|
'githooks/pre-push',
|
|
59
59
|
'githooks/post-merge',
|
|
60
60
|
'githooks/post-checkout',
|
|
61
|
-
'codex/skills/
|
|
61
|
+
'codex/skills/gitguardex/SKILL.md',
|
|
62
62
|
'codex/skills/guardex-merge-skills-to-dev/SKILL.md',
|
|
63
|
-
'claude/commands/
|
|
63
|
+
'claude/commands/gitguardex.md',
|
|
64
64
|
'github/pull.yml.example',
|
|
65
65
|
'github/workflows/cr.yml',
|
|
66
66
|
];
|
|
@@ -143,9 +143,9 @@ const MANAGED_GITIGNORE_PATHS = [
|
|
|
143
143
|
'.githooks/post-merge',
|
|
144
144
|
'.githooks/post-checkout',
|
|
145
145
|
'oh-my-codex/',
|
|
146
|
-
'.codex/skills/
|
|
146
|
+
'.codex/skills/gitguardex/SKILL.md',
|
|
147
147
|
'.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
|
|
148
|
-
'.claude/commands/
|
|
148
|
+
'.claude/commands/gitguardex.md',
|
|
149
149
|
LOCK_FILE_RELATIVE,
|
|
150
150
|
];
|
|
151
151
|
const OMX_SCAFFOLD_DIRECTORIES = [
|
|
@@ -196,7 +196,7 @@ const SUGGESTIBLE_COMMANDS = [
|
|
|
196
196
|
'release',
|
|
197
197
|
];
|
|
198
198
|
const CLI_COMMAND_DESCRIPTIONS = [
|
|
199
|
-
['status', 'Show
|
|
199
|
+
['status', 'Show GitGuardex CLI + service health without modifying files'],
|
|
200
200
|
['setup', 'Install, repair, and verify guardrails (flags: --repair, --install-only, --target)'],
|
|
201
201
|
['doctor', 'Repair drift + verify (auto-sandboxes on protected main)'],
|
|
202
202
|
['protect', 'Manage protected branches (list/add/remove/set/reset)'],
|
|
@@ -223,24 +223,20 @@ const AGENT_BOT_DESCRIPTIONS = [
|
|
|
223
223
|
['agents', 'Start/stop review + cleanup bots for this repo'],
|
|
224
224
|
];
|
|
225
225
|
|
|
226
|
-
const AI_SETUP_PROMPT = `
|
|
227
|
-
|
|
228
|
-
1) Install:
|
|
229
|
-
2) Bootstrap:
|
|
230
|
-
3)
|
|
231
|
-
4)
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
9) Sync: gx sync --check && gx sync (optional; rebase onto base)
|
|
241
|
-
10) Fork sync: cp .github/pull.yml.example .github/pull.yml (optional; install https://github.com/apps/pull)
|
|
242
|
-
11) PR review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY in Actions variables (uses .github/workflows/cr.yml)
|
|
243
|
-
12) GitHub repo: enable Settings -> PRs -> Automatically delete head branches
|
|
226
|
+
const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in this repo.
|
|
227
|
+
|
|
228
|
+
1) Install: npm i -g @imdeadpool/guardex && gh --version
|
|
229
|
+
2) Bootstrap: gx setup
|
|
230
|
+
3) Repair: gx doctor
|
|
231
|
+
4) Task loop: bash scripts/codex-agent.sh "<task>" "<agent>"
|
|
232
|
+
or branch-start -> claim -> branch-finish
|
|
233
|
+
5) Finish: gx finish --all
|
|
234
|
+
6) Cleanup: gx cleanup
|
|
235
|
+
7) OpenSpec: /opsx:propose -> /opsx:apply -> /opsx:archive
|
|
236
|
+
8) Optional: gx protect add release staging
|
|
237
|
+
9) Optional: gx sync --check && gx sync
|
|
238
|
+
10) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
|
|
239
|
+
11) Fork sync: cp .github/pull.yml.example .github/pull.yml
|
|
244
240
|
`;
|
|
245
241
|
|
|
246
242
|
const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
|
|
@@ -251,7 +247,7 @@ bash scripts/codex-agent.sh "<task>" "<agent>"
|
|
|
251
247
|
gx finish --all
|
|
252
248
|
gx cleanup
|
|
253
249
|
gx protect add release staging
|
|
254
|
-
gx sync
|
|
250
|
+
gx sync --check && gx sync
|
|
255
251
|
`;
|
|
256
252
|
|
|
257
253
|
const SCORECARD_RISK_BY_CHECK = {
|
|
@@ -320,10 +316,17 @@ function agentBotCatalogLines(indent = ' ') {
|
|
|
320
316
|
);
|
|
321
317
|
}
|
|
322
318
|
|
|
319
|
+
function repoToggleLines(indent = ' ') {
|
|
320
|
+
return [
|
|
321
|
+
`${indent}Set repo-root .env: ${GUARDEX_REPO_TOGGLE_ENV}=0 disables Guardex, ${GUARDEX_REPO_TOGGLE_ENV}=1 enables it again`,
|
|
322
|
+
];
|
|
323
|
+
}
|
|
324
|
+
|
|
323
325
|
function printToolLogsSummary() {
|
|
324
326
|
const usageLine = ` $ ${SHORT_TOOL_NAME} <command> [options]`;
|
|
325
327
|
const commandDetails = commandCatalogLines(' ');
|
|
326
328
|
const agentBotDetails = agentBotCatalogLines(' ');
|
|
329
|
+
const repoToggleDetails = repoToggleLines(' ');
|
|
327
330
|
|
|
328
331
|
if (!supportsAnsiColors()) {
|
|
329
332
|
console.log(`${TOOL_NAME}-tools logs:`);
|
|
@@ -337,6 +340,10 @@ function printToolLogsSummary() {
|
|
|
337
340
|
for (const line of agentBotDetails) {
|
|
338
341
|
console.log(line);
|
|
339
342
|
}
|
|
343
|
+
console.log(' REPO TOGGLE');
|
|
344
|
+
for (const line of repoToggleDetails) {
|
|
345
|
+
console.log(line);
|
|
346
|
+
}
|
|
340
347
|
return;
|
|
341
348
|
}
|
|
342
349
|
|
|
@@ -344,6 +351,7 @@ function printToolLogsSummary() {
|
|
|
344
351
|
const usageHeader = colorize('USAGE', '1');
|
|
345
352
|
const commandsHeader = colorize('COMMANDS', '1');
|
|
346
353
|
const agentBotHeader = colorize('AGENT BOT', '1');
|
|
354
|
+
const repoToggleHeader = colorize('REPO TOGGLE', '1');
|
|
347
355
|
const pipe = colorize('│', '90');
|
|
348
356
|
const tee = colorize('├', '90');
|
|
349
357
|
const corner = colorize('└', '90');
|
|
@@ -367,6 +375,14 @@ function printToolLogsSummary() {
|
|
|
367
375
|
}
|
|
368
376
|
console.log(` ${pipe}${line.slice(2)}`);
|
|
369
377
|
}
|
|
378
|
+
console.log(` ${tee}─ ${repoToggleHeader}`);
|
|
379
|
+
for (const line of repoToggleDetails) {
|
|
380
|
+
if (!line) {
|
|
381
|
+
console.log(` ${pipe}`);
|
|
382
|
+
continue;
|
|
383
|
+
}
|
|
384
|
+
console.log(` ${pipe}${line.slice(2)}`);
|
|
385
|
+
}
|
|
370
386
|
console.log(` ${corner}─ ${colorize(`Try '${TOOL_NAME} doctor' for one-step repair + verification.`, '2')}`);
|
|
371
387
|
}
|
|
372
388
|
|
|
@@ -387,6 +403,9 @@ ${commandCatalogLines().join('\n')}
|
|
|
387
403
|
AGENT BOT
|
|
388
404
|
${agentBotCatalogLines().join('\n')}
|
|
389
405
|
|
|
406
|
+
REPO TOGGLE
|
|
407
|
+
${repoToggleLines().join('\n')}
|
|
408
|
+
|
|
390
409
|
NOTES
|
|
391
410
|
- No command = ${SHORT_TOOL_NAME} status. ${SHORT_TOOL_NAME} init is an alias of ${SHORT_TOOL_NAME} setup.
|
|
392
411
|
- Global installs need Y/N approval; GitHub CLI (gh) is required for PR automation.
|
|
@@ -785,7 +804,7 @@ function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
|
|
|
785
804
|
if (!dryRun) {
|
|
786
805
|
fs.writeFileSync(agentsPath, next, 'utf8');
|
|
787
806
|
}
|
|
788
|
-
return { status: 'updated', file: 'AGENTS.md', note: 'refreshed
|
|
807
|
+
return { status: 'updated', file: 'AGENTS.md', note: 'refreshed gitguardex-managed block' };
|
|
789
808
|
}
|
|
790
809
|
|
|
791
810
|
if (existing.includes(AGENTS_MARKER_START)) {
|
|
@@ -816,7 +835,7 @@ function ensureManagedGitignore(repoRoot, dryRun) {
|
|
|
816
835
|
if (!dryRun) {
|
|
817
836
|
fs.writeFileSync(gitignorePath, `${managedBlock}\n`, 'utf8');
|
|
818
837
|
}
|
|
819
|
-
return { status: 'created', file: '.gitignore', note: 'added
|
|
838
|
+
return { status: 'created', file: '.gitignore', note: 'added gitguardex-managed entries' };
|
|
820
839
|
}
|
|
821
840
|
|
|
822
841
|
const existing = fs.readFileSync(gitignorePath, 'utf8');
|
|
@@ -828,14 +847,14 @@ function ensureManagedGitignore(repoRoot, dryRun) {
|
|
|
828
847
|
if (!dryRun) {
|
|
829
848
|
fs.writeFileSync(gitignorePath, next, 'utf8');
|
|
830
849
|
}
|
|
831
|
-
return { status: 'updated', file: '.gitignore', note: 'refreshed
|
|
850
|
+
return { status: 'updated', file: '.gitignore', note: 'refreshed gitguardex-managed entries' };
|
|
832
851
|
}
|
|
833
852
|
|
|
834
853
|
const separator = existing.endsWith('\n') ? '\n' : '\n\n';
|
|
835
854
|
if (!dryRun) {
|
|
836
855
|
fs.writeFileSync(gitignorePath, `${existing}${separator}${managedBlock}\n`, 'utf8');
|
|
837
856
|
}
|
|
838
|
-
return { status: 'updated', file: '.gitignore', note: 'appended
|
|
857
|
+
return { status: 'updated', file: '.gitignore', note: 'appended gitguardex-managed entries' };
|
|
839
858
|
}
|
|
840
859
|
|
|
841
860
|
function configureHooks(repoRoot, dryRun) {
|
package/package.json
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@imdeadpool/guardex",
|
|
3
|
-
"version": "7.0.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "7.0.10",
|
|
4
|
+
"description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"preferGlobal": true,
|
|
7
7
|
"bin": {
|
|
8
|
+
"gitguardex": "bin/multiagent-safety.js",
|
|
8
9
|
"guardex": "bin/multiagent-safety.js",
|
|
9
10
|
"gx": "bin/multiagent-safety.js",
|
|
10
11
|
"multiagent-safety": "bin/multiagent-safety.js"
|
|
@@ -43,6 +44,7 @@
|
|
|
43
44
|
"CONTRIBUTING.md"
|
|
44
45
|
],
|
|
45
46
|
"keywords": [
|
|
47
|
+
"gitguardex",
|
|
46
48
|
"guardex",
|
|
47
49
|
"multi-agent",
|
|
48
50
|
"git-hooks",
|
|
@@ -53,10 +55,10 @@
|
|
|
53
55
|
"author": "recodeecom",
|
|
54
56
|
"repository": {
|
|
55
57
|
"type": "git",
|
|
56
|
-
"url": "git+https://github.com/recodeee/
|
|
58
|
+
"url": "git+https://github.com/recodeee/gitguardex.git"
|
|
57
59
|
},
|
|
58
60
|
"bugs": {
|
|
59
|
-
"url": "https://github.com/recodeee/
|
|
61
|
+
"url": "https://github.com/recodeee/gitguardex/issues"
|
|
60
62
|
},
|
|
61
63
|
"homepage": "https://guardextutorial.com",
|
|
62
64
|
"funding": "https://github.com/sponsors/recodeecom",
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
<!-- multiagent-safety:START -->
|
|
2
2
|
## Multi-Agent Safety Contract
|
|
3
3
|
|
|
4
|
-
**Repo toggle.**
|
|
4
|
+
**Repo toggle.** `GUARDEX_ON=0|false|no|off` disables this contract. `GUARDEX_ON=1|true|yes|on` re-enables it.
|
|
5
5
|
|
|
6
|
-
**Isolation.**
|
|
6
|
+
**Isolation.** One task = one `agent/*` branch + worktree. Start `scripts/agent-branch-start.sh "<task>" "<agent>"`. Base branches stay read-only. No `git checkout` on primary worktrees; use `git worktree add`. `.githooks/post-checkout` auto-reverts primary-branch switches unless `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
|
|
7
7
|
|
|
8
|
-
**Ownership.**
|
|
8
|
+
**Ownership.** Claim before edits: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Delete only claimed paths.
|
|
9
9
|
|
|
10
|
-
**Handoff
|
|
10
|
+
**Handoff.** Post a one-line note before edits. Re-read latest handoffs before replacing nearby work.
|
|
11
11
|
|
|
12
|
-
**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup`
|
|
12
|
+
**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` or `gx finish --all`. Done = commit pushed, PR URL recorded, state=`MERGED`, sandbox pruned. If blocked, append `BLOCKED:` and stop.
|
|
13
13
|
|
|
14
|
-
**Parallel safety.**
|
|
14
|
+
**Parallel safety.** Never revert unrelated edits. Report conflicts.
|
|
15
15
|
|
|
16
|
-
**Reporting.**
|
|
16
|
+
**Reporting.** Completion handoff includes files changed, behavior touched, verification commands/results, and risks/follow-ups.
|
|
17
17
|
|
|
18
|
-
**OpenSpec
|
|
18
|
+
**OpenSpec.** Keep `openspec/changes/<slug>/tasks.md` current. End task scaffolds with PR merge + sandbox cleanup evidence. Run `openspec validate --specs` before archive.
|
|
19
19
|
|
|
20
20
|
**Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
|
|
21
21
|
<!-- multiagent-safety:END -->
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: gitguardex
|
|
3
|
+
description: "Repo guardrail check and repair."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Use when repo safety may be broken.
|
|
7
|
+
|
|
8
|
+
`gx status` -> `gx doctor` -> `gx status --strict`
|
|
9
|
+
|
|
10
|
+
Bootstrap: `gx setup`
|
|
11
|
+
Ops: `bash scripts/codex-agent.sh "<task>" "<agent>"`, `gx finish --all`, `gx cleanup`
|
|
@@ -89,5 +89,5 @@ The system SHALL enforce ${CAPABILITY_SLUG} behavior as defined by this change.
|
|
|
89
89
|
SPECEOF
|
|
90
90
|
fi
|
|
91
91
|
|
|
92
|
-
echo "[
|
|
93
|
-
echo "[
|
|
92
|
+
echo "[gitguardex] OpenSpec change workspace ready: ${CHANGE_DIR}"
|
|
93
|
+
echo "[gitguardex] OpenSpec change spec scaffold: ${SPEC_DIR}/spec.md"
|
|
@@ -114,5 +114,5 @@ Role workspace for \`${role}\`.
|
|
|
114
114
|
"
|
|
115
115
|
done
|
|
116
116
|
|
|
117
|
-
echo "[
|
|
118
|
-
echo "[
|
|
117
|
+
echo "[gitguardex] OpenSpec plan workspace ready: ${PLAN_DIR}"
|
|
118
|
+
echo "[gitguardex] Roles: ${ROLES[*]}"
|
|
@@ -1,12 +0,0 @@
|
|
|
1
|
-
# /guardex
|
|
2
|
-
|
|
3
|
-
Run a GuardeX check-and-repair for the current repo.
|
|
4
|
-
|
|
5
|
-
## Steps
|
|
6
|
-
|
|
7
|
-
1. `gx status` — if green, stop.
|
|
8
|
-
2. If degraded, `gx doctor`.
|
|
9
|
-
3. If still degraded, `gx status --strict` and summarize each finding with a fix.
|
|
10
|
-
4. Report verdict: `Repo is guarded` or `Repo is not guarded` (list blockers).
|
|
11
|
-
|
|
12
|
-
Keep output short, include the exact commands you ran.
|
|
@@ -1,43 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: guardex
|
|
3
|
-
description: "Check, repair, or bootstrap multi-agent safety guardrails in this repository."
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# GuardeX (Codex skill)
|
|
7
|
-
|
|
8
|
-
Use when branch safety, lock ownership, or guardrail setup may be broken.
|
|
9
|
-
|
|
10
|
-
## Fast path
|
|
11
|
-
|
|
12
|
-
1. `gx status` — one-glance health check.
|
|
13
|
-
2. If degraded, `gx doctor` — repair + verify in one pass.
|
|
14
|
-
3. If issues remain, `gx status --strict` and address each finding.
|
|
15
|
-
|
|
16
|
-
## Bootstrap (missing guardrails)
|
|
17
|
-
|
|
18
|
-
```sh
|
|
19
|
-
gx setup # install + repair + verify
|
|
20
|
-
gx status # confirm green
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
In a monorepo with nested git repos (top-level `.git` plus `apps/*/.git`), `gx setup` auto-installs into every discovered repo. Submodules and guardex-managed worktrees are skipped. Pass `--no-recursive` to limit to the top-level only.
|
|
24
|
-
|
|
25
|
-
## Notes
|
|
26
|
-
|
|
27
|
-
- Isolation: `scripts/codex-agent.sh "<task>" "<agent>"` is the one-command sandbox start/finish loop.
|
|
28
|
-
- Completion: auto-finish keeps the branch until explicit `gx cleanup`.
|
|
29
|
-
- Never bypass protected-branch safeguards.
|
|
30
|
-
|
|
31
|
-
## Bulk finish
|
|
32
|
-
|
|
33
|
-
```sh
|
|
34
|
-
gx finish --all # commit + PR + merge all ready agent/* branches
|
|
35
|
-
gx cleanup # prune merged/stale branches and worktrees
|
|
36
|
-
```
|
|
37
|
-
|
|
38
|
-
If a branch fails with stale rebase/worktree state:
|
|
39
|
-
|
|
40
|
-
```sh
|
|
41
|
-
git -C "<worktree>" rebase --abort || true
|
|
42
|
-
gx finish --branch "<agent-branch>" --cleanup
|
|
43
|
-
```
|