Ship the CLI-owned install surface on a fresh npm version

README.md

@@ -642,6 +642,12 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.18
+- GitGuardex now keeps the install workflow in `gx` itself: `gx branch ...`, `gx locks ...`, `gx worktree prune`, `gx migrate`, and user-level agent-skill install now own the agent lifecycle instead of teaching pasted repo scripts as the primary surface.
+- Fresh installs switch repo hooks to tiny `gx hook run ...` shims, stop copying repo-local workflow implementations and repo-local skills, and stop injecting Guardex-managed `agent:*` package scripts into consumer repos.
+- `gx migrate` can move older repos onto the smaller CLI-owned install surface while preserving the managed AGENTS block, lock registry state, repo-local dispatch shims, and required gitignore entries.
+- Bumped the release from `7.0.17` → `7.0.18` so the shipped CLI-owned install-surface changes land on a fresh publishable npm version.
+
 ### v7.0.17
 - Restored the published npm package name to `@imdeadpool/guardex` after the `@imdeadpool/gitguardex` rename only changed the package identity locally and could not rename the existing npm registry entry.
 - README/install/tutorial/self-update surfaces now point back at `@imdeadpool/guardex` while keeping GitGuardex as the product/repo brand and `gitguardex` as the long-form command.

openspec/changes/agent-codex-release-cli-owned-install-surface-v7-0-1-2026-04-22-00-53/notes.md

@@ -0,0 +1,10 @@
+# agent-codex-release-cli-owned-install-surface-v7-0-1-2026-04-22-00-53 (minimal / T1)
+
+- Bump the package metadata from `7.0.17` to `7.0.18` so the CLI-owned install-surface changes can ship under a fresh publishable npm version.
+- Add a `README.md` release-notes entry for `v7.0.18` that documents the shipped `gx`-owned branch/lock/worktree/migrate surface, hook shims, smaller repo footprint, and user-level agent-skill install path.
+- Keep the release scoped to metadata and operator-facing release history only; no runtime behavior changes are introduced in this follow-up.
+- Verification:
+  - `node --check bin/multiagent-safety.js`
+  - `npm pack --dry-run`
+  - `openspec validate --specs`
+  - `openspec validate agent-codex-release-cli-owned-install-surface-v7-0-1-2026-04-22-00-53 --type change --strict` is intentionally not applicable to this T1 notes-only change because there are no delta specs.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.17",
+  "version": "7.0.18",
   "description": "Guardian T-Rex for your multi-agent repo. Isolated worktrees, file locks, and PR-only merges stop parallel Codex & Claude agents from overwriting each other's work. Auto-wires Oh My Codex, Oh My Claude, OpenSpec, and Caveman.",
   "license": "MIT",
   "preferGlobal": true,

scripts/openspec/init-change-workspace.sh

@@ -74,11 +74,11 @@ Describe the change in a sentence or two. Commit message is the spec of record.
 ## Handoff
 
 - Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
-- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/notes.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`bash scripts/agent-branch-finish.sh --branch "${AGENT_BRANCH}" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/notes.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
 
 ## Cleanup
 
-- [ ] Run: \`bash scripts/agent-branch-finish.sh --branch "${AGENT_BRANCH}" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`
+- [ ] Run: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`
 - [ ] Record PR URL + \`MERGED\` state in the completion handoff.
 - [ ] Confirm sandbox worktree is gone (\`git worktree list\`, \`git branch -a\`).
 NOTESEOF
@@ -117,7 +117,7 @@ This change is complete only when **all** of the following are true:
 ## Handoff
 
 - Handoff: change=\`${CHANGE_SLUG}\`; branch=\`${AGENT_BRANCH}\`; scope=\`TODO\`; action=\`continue this sandbox or finish cleanup after a usage-limit/manual takeover\`.
-- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/tasks.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`bash scripts/agent-branch-finish.sh --branch "${AGENT_BRANCH}" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
+- Copy prompt: Continue \`${CHANGE_SLUG}\` on branch \`${AGENT_BRANCH}\`. Work inside the existing sandbox, review \`openspec/changes/${CHANGE_SLUG}/tasks.md\`, continue from the current state instead of creating a new sandbox, and when the work is done run \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`.
 
 ## 1. Specification
 
@@ -137,7 +137,7 @@ This change is complete only when **all** of the following are true:
 
 ## 4. Cleanup (mandatory; run before claiming completion)
 
-- [ ] 4.1 Run the cleanup pipeline: \`bash scripts/agent-branch-finish.sh --branch "${AGENT_BRANCH}" --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
+- [ ] 4.1 Run the cleanup pipeline: \`gx branch finish --branch ${AGENT_BRANCH} --base ${BASE_BRANCH} --via-pr --wait-for-merge --cleanup\`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation.
 - [ ] 4.2 Record the PR URL and final merge state (\`MERGED\`) in the completion handoff.
 - [ ] 4.3 Confirm the sandbox worktree is gone (\`git worktree list\` no longer shows the agent path; \`git branch -a\` shows no surviving local/remote refs for the branch).
 TASKSEOF

scripts/openspec/init-plan-workspace.sh

@@ -434,7 +434,7 @@ EXCCPTEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -470,7 +470,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -506,7 +506,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -542,7 +542,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -578,7 +578,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -614,7 +614,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF
@@ -650,7 +650,7 @@ TASKEOF
 
 ## 6. Cleanup
 
-- [ ] 6.1 If this lane owns finalization, run \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
+- [ ] 6.1 If this lane owns finalization, run \`gx branch finish --branch <agent-branch> --base dev --via-pr --wait-for-merge --cleanup\`.
 - [ ] 6.2 Record PR URL + final \`MERGED\` state in the handoff.
 - [ ] 6.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or append \`BLOCKED:\` and stop.
 TASKEOF

test/merge-workflow.test.js

@@ -40,7 +40,13 @@ function runCmd(cmd, args, cwd, extraEnv = {}) {
   return cp.spawnSync(cmd, args, {
     cwd,
     encoding: 'utf8',
-    env: { ...sanitizedEnv, ...pushBypassEnv, ...extraEnv },
+    env: {
+      ...sanitizedEnv,
+      GUARDEX_CLI_ENTRY: cliPath,
+      GUARDEX_NODE_BIN: process.execPath,
+      ...pushBypassEnv,
+      ...extraEnv,
+    },
   });
 }
 
@@ -127,7 +133,7 @@ function extractMergeTargetWorktree(output) {
   return match[1].trim();
 }
 
-test('setup installs the managed merge workflow script and package entry', () => {
+test('setup installs the managed merge workflow shim without package script churn', () => {
   const repoDir = initRepo();
   seedCommit(repoDir);
 
@@ -139,7 +145,7 @@ test('setup installs the managed merge workflow script and package entry', () =>
   fs.accessSync(mergeScriptPath, fs.constants.X_OK);
 
   const packageJson = JSON.parse(fs.readFileSync(path.join(repoDir, 'package.json'), 'utf8'));
-  assert.equal(packageJson.scripts['agent:branch:merge'], 'bash ./scripts/agent-branch-merge.sh');
+  assert.equal(packageJson.scripts['agent:branch:merge'], undefined);
 });
 
 test('merge command creates an integration lane, reports overlaps, and merges cleanly', () => {