@imdeadpool/guardex 7.0.13 → 7.0.14

package/README.md

@@ -507,6 +507,10 @@ npm pack --dry-run
 <details>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.14
+- Bumped `@imdeadpool/guardex` from `7.0.13` → `7.0.14` after npm rejected a republish over the already-published `7.0.13`.
+- No package payload changes beyond the release metadata bump; this release exists so `npm publish` can proceed with a fresh semver.
+
 ### v7.0.13
 - `gx status` and `gx setup` now present the Claude companion as `oh-my-claudecode` while still installing the published npm package `oh-my-claude-sisyphus`.
 - When that dependency is inactive or the user declines the optional install, Guardex now prints the upstream repo URL so the missing dependency is explicit instead of hidden behind the npm package name.

package/bin/multiagent-safety.js

@@ -115,15 +115,26 @@ const REQUIRED_WORKFLOW_FILES = [
 ];
 
 const REQUIRED_PACKAGE_SCRIPTS = {
+  'agent:codex': 'bash ./scripts/codex-agent.sh',
   'agent:branch:start': 'bash ./scripts/agent-branch-start.sh',
   'agent:branch:finish': 'bash ./scripts/agent-branch-finish.sh',
-  'agent:cleanup': 'bash ./scripts/agent-worktree-prune.sh',
+  'agent:cleanup': 'gx cleanup',
   'agent:hooks:install': 'bash ./scripts/install-agent-git-hooks.sh',
   'agent:locks:claim': 'python3 ./scripts/agent-file-locks.py claim',
+  'agent:locks:allow-delete': 'python3 ./scripts/agent-file-locks.py allow-delete',
   'agent:locks:release': 'python3 ./scripts/agent-file-locks.py release',
   'agent:locks:status': 'python3 ./scripts/agent-file-locks.py status',
   'agent:plan:init': 'bash ./scripts/openspec/init-plan-workspace.sh',
   'agent:change:init': 'bash ./scripts/openspec/init-change-workspace.sh',
+  'agent:protect:list': 'gx protect list',
+  'agent:branch:sync': 'gx sync',
+  'agent:branch:sync:check': 'gx sync --check',
+  'agent:safety:setup': 'gx setup',
+  'agent:safety:scan': 'gx status --strict',
+  'agent:safety:fix': 'gx setup --repair',
+  'agent:safety:doctor': 'gx doctor',
+  'agent:review:watch': 'bash ./scripts/review-bot-watch.sh',
+  'agent:finish': 'gx finish --all',
 };
 
 const EXECUTABLE_RELATIVE_PATHS = new Set([
@@ -165,26 +176,15 @@ const GITIGNORE_MARKER_END = '# multiagent-safety:END';
 const MANAGED_GITIGNORE_PATHS = [
   '.omx/',
   '.omc/',
-  '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/guardex-env.sh',
-  'scripts/install-agent-git-hooks.sh',
-  'scripts/openspec/init-plan-workspace.sh',
-  'scripts/openspec/init-change-workspace.sh',
-  '.githooks/pre-commit',
-  '.githooks/pre-push',
-  '.githooks/post-merge',
-  '.githooks/post-checkout',
+  'scripts/*',
+  '.githooks',
   'oh-my-codex/',
   '.codex/skills/gitguardex/SKILL.md',
   '.codex/skills/guardex-merge-skills-to-dev/SKILL.md',
   '.claude/commands/gitguardex.md',
   LOCK_FILE_RELATIVE,
 ];
+const REPO_SCAFFOLD_DIRECTORIES = ['bin'];
 const OMX_SCAFFOLD_DIRECTORIES = [
   '.omx',
   '.omx/state',
@@ -266,14 +266,14 @@ const AI_SETUP_PROMPT = `GitGuardex (gx) setup checklist for Codex/Claude in thi
 2) Bootstrap:  gx setup
 3) Repair:     gx doctor
 4) Task loop:  bash scripts/codex-agent.sh "<task>" "<agent>"
-               or branch-start -> claim -> branch-finish
+               or branch-start -> python3 scripts/agent-file-locks.py claim -> branch-finish
 5) Finish:     gx finish --all
 6) Cleanup:    gx cleanup
 7) OpenSpec:   /opsx:propose -> /opsx:apply -> /opsx:archive
 8) Optional:   gx protect add release staging
 9) Optional:   gx sync --check && gx sync
 10) Review bot: install https://github.com/apps/cr-gpt + set OPENAI_API_KEY
-11) Fork sync:  cp .github/pull.yml.example .github/pull.yml
+11) Fork sync:  install https://github.com/apps/pull + cp .github/pull.yml.example .github/pull.yml
 `;
 
 const AI_SETUP_COMMANDS = `npm i -g @imdeadpool/guardex
@@ -281,6 +281,7 @@ gh --version
 gx setup
 gx doctor
 bash scripts/codex-agent.sh "<task>" "<agent>"
+python3 scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>
 gx finish --all
 gx cleanup
 gx protect add release staging
@@ -598,9 +599,27 @@ function toDestinationPath(relativeTemplatePath) {
   throw new Error(`Unsupported template path: ${relativeTemplatePath}`);
 }
 
-function ensureParentDir(filePath, dryRun) {
+function ensureParentDir(repoRoot, filePath, dryRun) {
   if (dryRun) return;
-  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+
+  const parentDir = path.dirname(filePath);
+  const relativeParentDir = path.relative(repoRoot, parentDir);
+  const segments = relativeParentDir.split(path.sep).filter(Boolean);
+  let currentPath = repoRoot;
+
+  for (const segment of segments) {
+    currentPath = path.join(currentPath, segment);
+    if (fs.existsSync(currentPath) && !fs.statSync(currentPath).isDirectory()) {
+      const blockingPath = path.relative(repoRoot, currentPath) || path.basename(currentPath);
+      const targetPath = path.relative(repoRoot, filePath) || path.basename(filePath);
+      throw new Error(
+        `Path conflict: ${blockingPath} exists as a file, but ${targetPath} needs it to be a directory. ` +
+        `Remove or rename ${blockingPath} and rerun '${SHORT_TOOL_NAME} setup'.`,
+      );
+    }
+  }
+
+  fs.mkdirSync(parentDir, { recursive: true });
 }
 
 function ensureExecutable(destinationPath, relativePath, dryRun) {
@@ -635,7 +654,7 @@ function copyTemplateFile(repoRoot, relativeTemplatePath, force, dryRun) {
     }
   }
 
-  ensureParentDir(destinationPath, dryRun);
+  ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
     fs.writeFileSync(destinationPath, sourceContent, 'utf8');
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
@@ -673,7 +692,7 @@ function ensureTemplateFilePresent(repoRoot, relativeTemplatePath, dryRun) {
     return { status: 'skipped-conflict', file: destinationRelativePath };
   }
 
-  ensureParentDir(destinationPath, dryRun);
+  ensureParentDir(repoRoot, destinationPath, dryRun);
   if (!dryRun) {
     fs.writeFileSync(destinationPath, sourceContent, 'utf8');
     ensureExecutable(destinationPath, destinationRelativePath, dryRun);
@@ -689,6 +708,22 @@ function lockFilePath(repoRoot) {
 function ensureOmxScaffold(repoRoot, dryRun) {
   const operations = [];
 
+  for (const relativeDir of REPO_SCAFFOLD_DIRECTORIES) {
+    const absoluteDir = path.join(repoRoot, relativeDir);
+    if (fs.existsSync(absoluteDir)) {
+      if (!fs.statSync(absoluteDir).isDirectory()) {
+        throw new Error(`Expected directory at ${relativeDir} but found a file.`);
+      }
+      operations.push({ status: 'unchanged', file: relativeDir });
+      continue;
+    }
+
+    if (!dryRun) {
+      fs.mkdirSync(absoluteDir, { recursive: true });
+    }
+    operations.push({ status: 'created', file: relativeDir });
+  }
+
   for (const relativeDir of OMX_SCAFFOLD_DIRECTORIES) {
     const absoluteDir = path.join(repoRoot, relativeDir);
     if (fs.existsSync(absoluteDir)) {
@@ -976,10 +1011,9 @@ function parseCommonArgs(rawArgs, defaults) {
   return options;
 }
 
-function parseSetupArgs(rawArgs, defaults) {
-  const setupDefaults = {
+function parseRepoTraversalArgs(rawArgs, defaults) {
+  const traversalDefaults = {
     ...defaults,
-    parentWorkspaceView: false,
     recursive: true,
     nestedMaxDepth: NESTED_REPO_DEFAULT_MAX_DEPTH,
     nestedSkipDirs: [],
@@ -989,20 +1023,12 @@ function parseSetupArgs(rawArgs, defaults) {
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
-    if (arg === '--parent-workspace-view') {
-      setupDefaults.parentWorkspaceView = true;
-      continue;
-    }
-    if (arg === '--no-parent-workspace-view') {
-      setupDefaults.parentWorkspaceView = false;
-      continue;
-    }
     if (arg === '--no-recursive' || arg === '--no-nested' || arg === '--single-repo') {
-      setupDefaults.recursive = false;
+      traversalDefaults.recursive = false;
       continue;
     }
     if (arg === '--recursive' || arg === '--nested') {
-      setupDefaults.recursive = true;
+      traversalDefaults.recursive = true;
       continue;
     }
     if (arg === '--max-depth') {
@@ -1011,47 +1037,60 @@ function parseSetupArgs(rawArgs, defaults) {
       if (!Number.isFinite(parsed) || parsed < 1) {
         throw new Error('--max-depth requires a positive integer');
       }
-      setupDefaults.nestedMaxDepth = parsed;
+      traversalDefaults.nestedMaxDepth = parsed;
       index += 1;
       continue;
     }
     if (arg === '--skip-nested') {
       const raw = requireValue(rawArgs, index, '--skip-nested');
-      setupDefaults.nestedSkipDirs.push(raw);
+      traversalDefaults.nestedSkipDirs.push(raw);
       index += 1;
       continue;
     }
     if (arg === '--include-submodules') {
-      setupDefaults.includeSubmodules = true;
+      traversalDefaults.includeSubmodules = true;
       continue;
     }
     forwardedArgs.push(arg);
   }
 
-  return parseCommonArgs(forwardedArgs, setupDefaults);
+  return parseCommonArgs(forwardedArgs, traversalDefaults);
 }
 
-function parseDoctorArgs(rawArgs) {
-  const options = {
-    target: process.cwd(),
-    strict: false,
+function parseSetupArgs(rawArgs, defaults) {
+  const setupDefaults = {
+    ...defaults,
+    parentWorkspaceView: false,
   };
+  const forwardedArgs = [];
 
   for (let index = 0; index < rawArgs.length; index += 1) {
     const arg = rawArgs[index];
-    if (arg === '--target' || arg === '-t') {
-      options.target = requireValue(rawArgs, index, '--target');
-      index += 1;
+    if (arg === '--parent-workspace-view') {
+      setupDefaults.parentWorkspaceView = true;
       continue;
     }
-    if (arg === '--strict') {
-      options.strict = true;
+    if (arg === '--no-parent-workspace-view') {
+      setupDefaults.parentWorkspaceView = false;
       continue;
     }
-    throw new Error(`Unknown option: ${arg}`);
+    forwardedArgs.push(arg);
   }
 
-  return options;
+  return parseRepoTraversalArgs(forwardedArgs, setupDefaults);
+}
+
+function parseDoctorArgs(rawArgs) {
+  return parseRepoTraversalArgs(rawArgs, {
+    target: process.cwd(),
+    dropStaleLocks: true,
+    skipAgents: false,
+    skipPackageJson: false,
+    skipGitignore: false,
+    dryRun: false,
+    json: false,
+    allowProtectedBaseWrite: false,
+  });
 }
 
 function normalizeWorkspacePath(relativePath) {
@@ -1541,7 +1580,7 @@ function finishDoctorSandboxBranch(blocked, metadata) {
 
   const finishResult = run(
     'bash',
-    [finishScript, '--branch', metadata.branch, '--via-pr', '--wait-for-merge'],
+    [finishScript, '--branch', metadata.branch, '--base', blocked.branch, '--via-pr', '--wait-for-merge'],
     { cwd: metadata.worktreePath, timeout: finishTimeoutMs },
   );
   if (isSpawnFailure(finishResult)) {
@@ -1580,6 +1619,33 @@ function finishDoctorSandboxBranch(blocked, metadata) {
   };
 }
 
+function syncProtectedBaseDoctorRepairs(options, blocked) {
+  const fixPayload = runFixInternal({
+    ...options,
+    target: blocked.repoRoot,
+    allowProtectedBaseWrite: true,
+  });
+  const changedOperations = fixPayload.operations.filter(
+    (operation) => !['unchanged', 'skipped'].includes(operation.status),
+  );
+  const hookChanged = fixPayload.hookResult?.status && fixPayload.hookResult.status !== 'unchanged';
+  const changedCount = changedOperations.length + (hookChanged ? 1 : 0);
+
+  if (changedCount === 0) {
+    return {
+      status: 'unchanged',
+      note: 'managed repair files already aligned in protected branch workspace',
+      fixPayload,
+    };
+  }
+
+  return {
+    status: options.dryRun ? 'would-sync' : 'synced',
+    note: `${options.dryRun ? 'would sync' : 'synced'} ${changedCount} managed repair item(s)`,
+    fixPayload,
+  };
+}
+
 function runDoctorInSandbox(options, blocked) {
   const startResult = startDoctorSandbox(blocked);
   const metadata = startResult.metadata;
@@ -1603,6 +1669,10 @@ function runDoctorInSandbox(options, blocked) {
     note: 'sandbox doctor did not complete successfully',
   };
 
+  let protectedBaseRepairSyncResult = {
+    status: 'skipped',
+    note: 'sandbox doctor did not complete successfully',
+  };
   let lockSyncResult = {
     status: 'skipped',
     note: 'sandbox doctor did not complete successfully',
@@ -1620,6 +1690,7 @@ function runDoctorInSandbox(options, blocked) {
     note: 'sandbox doctor did not complete successfully',
   };
   if (nestedResult.status === 0) {
+    protectedBaseRepairSyncResult = syncProtectedBaseDoctorRepairs(options, blocked);
     const omxScaffoldOps = ensureOmxScaffold(blocked.repoRoot, Boolean(options.dryRun));
     const changedOmxPaths = omxScaffoldOps.filter((operation) => operation.status !== 'unchanged');
     if (changedOmxPaths.length === 0) {
@@ -1708,6 +1779,7 @@ function runDoctorInSandbox(options, blocked) {
             JSON.stringify(
               {
                 ...parsed,
+                protectedBaseRepairSync: protectedBaseRepairSyncResult,
                 sandboxOmxScaffoldSync: omxScaffoldSyncResult,
                 sandboxLockSync: lockSyncResult,
                 sandboxAutoCommit: autoCommitResult,
@@ -1748,6 +1820,16 @@ function runDoctorInSandbox(options, blocked) {
         console.log(`[${TOOL_NAME}] Doctor sandbox auto-commit skipped: ${autoCommitResult.note}.`);
       }
 
+      if (protectedBaseRepairSyncResult.status === 'synced') {
+        console.log(`[${TOOL_NAME}] Synced repaired managed files back to protected branch workspace.`);
+      } else if (protectedBaseRepairSyncResult.status === 'unchanged') {
+        console.log(`[${TOOL_NAME}] Protected branch workspace already had the repaired managed files.`);
+      } else if (protectedBaseRepairSyncResult.status === 'would-sync') {
+        console.log(`[${TOOL_NAME}] Dry run: would sync repaired managed files back to protected branch workspace.`);
+      } else {
+        console.log(`[${TOOL_NAME}] Protected branch workspace repair sync skipped: ${protectedBaseRepairSyncResult.note}.`);
+      }
+
       if (finishResult.status === 'completed') {
         console.log(`[${TOOL_NAME}] Auto-finish flow completed for sandbox branch '${metadata.branch}'.`);
         if (finishResult.stdout) process.stdout.write(finishResult.stdout);
@@ -3897,6 +3979,10 @@ function runInstallInternal(options) {
   }
   const operations = [];
 
+  if (!options.skipGitignore) {
+    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
+  }
+
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
@@ -3904,9 +3990,6 @@ function runInstallInternal(options) {
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
-  if (!options.skipGitignore) {
-    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
-  }
 
   if (!options.skipPackageJson) {
     operations.push(ensurePackageScripts(repoRoot, Boolean(options.dryRun), { force: Boolean(options.force) }));
@@ -3941,6 +4024,10 @@ function runFixInternal(options) {
   }
   const operations = [];
 
+  if (!options.skipGitignore) {
+    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
+  }
+
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
 
   for (const templateFile of TEMPLATE_FILES) {
@@ -3948,9 +4035,6 @@ function runFixInternal(options) {
   }
 
   operations.push(ensureLockRegistry(repoRoot, Boolean(options.dryRun)));
-  if (!options.skipGitignore) {
-    operations.push(ensureManagedGitignore(repoRoot, Boolean(options.dryRun)));
-  }
 
   const lockState = lockStateOrError(repoRoot);
   if (!lockState.ok) {
@@ -4421,26 +4505,116 @@ function scan(rawArgs) {
 }
 
 function doctor(rawArgs) {
-  const options = parseCommonArgs(rawArgs, {
-    target: process.cwd(),
-    dropStaleLocks: true,
-    skipAgents: false,
-    skipPackageJson: false,
-    skipGitignore: false,
-    dryRun: false,
-    json: false,
-    allowProtectedBaseWrite: false,
-  });
+  const options = parseDoctorArgs(rawArgs);
+  const topRepoRoot = resolveRepoRoot(options.target);
+  const discoveredRepos = options.recursive
+    ? discoverNestedGitRepos(topRepoRoot, {
+      maxDepth: options.nestedMaxDepth,
+      extraSkip: options.nestedSkipDirs,
+      includeSubmodules: options.includeSubmodules,
+    })
+    : [topRepoRoot];
+
+  if (discoveredRepos.length > 1) {
+    if (!options.json) {
+      console.log(
+        `[${TOOL_NAME}] Detected ${discoveredRepos.length} git repos under ${topRepoRoot}. ` +
+        `Repairing each with doctor (use --single-repo to limit to the target).`,
+      );
+    }
 
-  const blocked = protectedBaseWriteBlock(options, { requireBootstrap: false });
+    const repoResults = [];
+    let aggregateExitCode = 0;
+    for (const repoPath of discoveredRepos) {
+      if (!options.json) {
+        console.log(`[${TOOL_NAME}] ── Doctor target: ${repoPath} ──`);
+      }
+
+      const nestedResult = run(
+        process.execPath,
+        [
+          path.resolve(__filename),
+          'doctor',
+          '--single-repo',
+          '--target',
+          repoPath,
+          ...(options.dropStaleLocks ? [] : ['--keep-stale-locks']),
+          ...(options.skipAgents ? ['--skip-agents'] : []),
+          ...(options.skipPackageJson ? ['--skip-package-json'] : []),
+          ...(options.skipGitignore ? ['--no-gitignore'] : []),
+          ...(options.dryRun ? ['--dry-run'] : []),
+          ...(options.json ? ['--json'] : []),
+          ...(options.allowProtectedBaseWrite ? ['--allow-protected-base-write'] : []),
+        ],
+        { cwd: topRepoRoot },
+      );
+      if (isSpawnFailure(nestedResult)) {
+        throw nestedResult.error;
+      }
+
+      const exitCode = typeof nestedResult.status === 'number' ? nestedResult.status : 1;
+      if (exitCode !== 0 && aggregateExitCode === 0) {
+        aggregateExitCode = exitCode;
+      }
+
+      if (options.json) {
+        let parsedResult = null;
+        if (nestedResult.stdout) {
+          try {
+            parsedResult = JSON.parse(nestedResult.stdout);
+          } catch {
+            parsedResult = null;
+          }
+        }
+        repoResults.push(
+          parsedResult
+            ? { repoRoot: repoPath, exitCode, result: parsedResult }
+            : {
+              repoRoot: repoPath,
+              exitCode,
+              stdout: nestedResult.stdout || '',
+              stderr: nestedResult.stderr || '',
+            },
+        );
+      } else {
+        if (nestedResult.stdout) process.stdout.write(nestedResult.stdout);
+        if (nestedResult.stderr) process.stderr.write(nestedResult.stderr);
+        process.stdout.write('\n');
+      }
+    }
+
+    if (options.json) {
+      process.stdout.write(
+        JSON.stringify(
+          {
+            repoRoot: topRepoRoot,
+            recursive: true,
+            repos: repoResults,
+          },
+          null,
+          2,
+        ) + '\n',
+      );
+    }
+
+    process.exitCode = aggregateExitCode;
+    return;
+  }
+
+  const singleRepoOptions = {
+    ...options,
+    target: topRepoRoot,
+  };
+
+  const blocked = protectedBaseWriteBlock(singleRepoOptions, { requireBootstrap: false });
   if (blocked) {
-    runDoctorInSandbox(options, blocked);
+    runDoctorInSandbox(singleRepoOptions, blocked);
     return;
   }
 
-  assertProtectedMainWriteAllowed(options, 'doctor');
-  const fixPayload = runFixInternal(options);
-  const scanResult = runScanInternal({ target: options.target, json: false });
+  assertProtectedMainWriteAllowed(singleRepoOptions, 'doctor');
+  const fixPayload = runFixInternal(singleRepoOptions);
+  const scanResult = runScanInternal({ target: singleRepoOptions.target, json: false });
   const currentBaseBranch = currentBranchName(scanResult.repoRoot);
   const autoFinishSummary = scanResult.guardexEnabled === false
     ? {
@@ -4453,12 +4627,12 @@ function doctor(rawArgs) {
     }
     : autoFinishReadyAgentBranches(scanResult.repoRoot, {
       baseBranch: currentBaseBranch,
-      dryRun: options.dryRun,
+      dryRun: singleRepoOptions.dryRun,
     });
   const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
 
-  if (options.json) {
+  if (singleRepoOptions.json) {
     process.stdout.write(
       JSON.stringify(
         {
@@ -4469,7 +4643,7 @@ function doctor(rawArgs) {
           fix: {
             operations: fixPayload.operations,
             hookResult: fixPayload.hookResult,
-            dryRun: Boolean(options.dryRun),
+            dryRun: Boolean(singleRepoOptions.dryRun),
           },
           scan: {
             guardexEnabled: scanResult.guardexEnabled !== false,
@@ -4488,7 +4662,7 @@ function doctor(rawArgs) {
     return;
   }
 
-  printOperations('Doctor/fix', fixPayload, options.dryRun);
+  printOperations('Doctor/fix', fixPayload, singleRepoOptions.dryRun);
   printScanResult(scanResult, false);
   if (scanResult.guardexEnabled === false) {
     console.log(`[${TOOL_NAME}] Repo-local Guardex enforcement is intentionally disabled.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.13",
+  "version": "7.0.14",
   "description": "GitGuardex: hardened multi-agent git guardrails for parallel agent work.",
   "license": "MIT",
   "preferGlobal": true,

package/templates/AGENTS.multiagent-safety.md

@@ -1,21 +1,28 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Safety Contract
+## Multi-Agent Execution Contract (GX)
 
-**Repo toggle.** `GUARDEX_ON=0|false|no|off` disables this contract. `GUARDEX_ON=1|true|yes|on` re-enables it.
+**Repo toggle.** Guardex is enabled by default. If the repo root `.env` sets `GUARDEX_ON=0`, `false`, `no`, or `off`, treat this entire Guardex contract as disabled for the repo and do not require Guardex worktrees, lock claims, completion flow, or OpenSpec workflow until `GUARDEX_ON` is re-enabled.
 
-**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`.
+**Repo toggle examples.** Add one of these lines to the repo-root `.env` file:
+`GUARDEX_ON=0` disables Guardex for that repo.
+`GUARDEX_ON=1` explicitly enables Guardex for that repo again.
 
-**Ownership.** Claim before edits: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Delete only claimed paths.
+**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `scripts/agent-branch-start.sh "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. Never `git checkout <branch>` on a primary working tree (including nested repos); use `git worktree add` instead. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions - bypass only with `GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH=1`.
+For every new task, including follow-up work in the same chat/session, if an assigned agent sub-branch/worktree is already open, continue in that sub-branch instead of creating a fresh lane unless the user explicitly redirects scope.
+Never implement directly on the local/base branch checkout; keep it unchanged and perform all edits in the agent sub-branch/worktree.
 
-**Handoff.** Post a one-line note before edits. Re-read latest handoffs before replacing nearby work.
+**Ownership.** Before editing, claim files: `scripts/agent-file-locks.py claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
 
-**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.
+**Handoff gate.** Post a one-line handoff note (plan/change, owned scope, intended action) before editing. Re-read the latest handoffs before replacing others' code.
 
-**Parallel safety.** Never revert unrelated edits. Report conflicts.
+**Completion.** Finish with `scripts/agent-branch-finish.sh --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`). Task is only complete when: commit pushed, PR URL recorded, state = `MERGED`, sandbox worktree pruned. If anything blocks, append a `BLOCKED:` note and stop - don't half-finish.
+OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete.
 
-**Reporting.** Completion handoff includes files changed, behavior touched, verification commands/results, and risks/follow-ups.
+**Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
 
-**OpenSpec.** Keep `openspec/changes/<slug>/tasks.md` current. End task scaffolds with PR merge + sandbox cleanup evidence. Run `openspec validate --specs` before archive.
+**Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
+
+**OpenSpec (when change-driven).** Keep `openspec/changes/<slug>/tasks.md` checkboxes current during work, not batched at the end. Task scaffolds and manual task edits must include an explicit final completion/cleanup section that ends with PR merge + sandbox cleanup (`gx finish --via-pr --wait-for-merge --cleanup` or `scripts/agent-branch-finish.sh ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
 
 **Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/github/workflows/cr.yml

@@ -10,12 +10,18 @@ permissions:
 
 jobs:
   review:
-    if: ${{ secrets.OPENAI_API_KEY != '' }}
     runs-on: ubuntu-latest
+    env:
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
     steps:
-      - uses: anc95/ChatGPT-CodeReview@main
+      - name: Skip when OPENAI_API_KEY is missing
+        if: ${{ env.OPENAI_API_KEY == '' }}
+        run: echo "OPENAI_API_KEY is not configured; skipping Code Review workflow."
+
+      - uses: anc95/ChatGPT-CodeReview@1e3df152c1b85c12da580b206c91ad343460c584 # v1.0.23
+        if: ${{ env.OPENAI_API_KEY != '' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_API_KEY: ${{ env.OPENAI_API_KEY }}
           OPENAI_API_ENDPOINT: https://api.openai.com/v1
           MODEL: gpt-4o-mini

package/templates/scripts/agent-worktree-prune.sh

@@ -8,11 +8,16 @@ FORCE_DIRTY=0
 DELETE_BRANCHES=0
 DELETE_REMOTE_BRANCHES=0
 ONLY_DIRTY_WORKTREES=0
+INCLUDE_PR_MERGED=0
 TARGET_BRANCH=""
 IDLE_MINUTES=0
 NOW_EPOCH_RAW="${GUARDEX_PRUNE_NOW_EPOCH:-}"
 IDLE_SECONDS=0
 NOW_EPOCH=0
+GH_BIN="${GUARDEX_GH_BIN:-gh}"
+PR_MERGED_LOOKUP_DISABLED=0
+PR_MERGED_LOOKUP_LOADED=0
+declare -A MERGED_PR_BRANCHES=()
 
 if [[ -n "$BASE_BRANCH" ]]; then
   BASE_BRANCH_EXPLICIT=1
@@ -45,6 +50,10 @@ while [[ $# -gt 0 ]]; do
       ONLY_DIRTY_WORKTREES=1
       shift
       ;;
+    --include-pr-merged)
+      INCLUDE_PR_MERGED=1
+      shift
+      ;;
     --branch)
       TARGET_BRANCH="${2:-}"
       shift 2
@@ -55,7 +64,7 @@ while [[ $# -gt 0 ]]; do
       ;;
     *)
       echo "[agent-worktree-prune] Unknown argument: $1" >&2
-      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
+      echo "Usage: $0 [--base <branch>] [--dry-run] [--force-dirty] [--delete-branches] [--delete-remote-branches] [--only-dirty-worktrees] [--include-pr-merged] [--branch <agent/...>] [--idle-minutes <minutes>]" >&2
       exit 1
       ;;
   esac
@@ -101,6 +110,44 @@ resolve_base_branch() {
   printf '%s' ""
 }
 
+load_merged_pr_branches() {
+  if [[ "$INCLUDE_PR_MERGED" -ne 1 ]]; then
+    return 1
+  fi
+  if [[ "$PR_MERGED_LOOKUP_DISABLED" -eq 1 ]]; then
+    return 1
+  fi
+  if [[ "$PR_MERGED_LOOKUP_LOADED" -eq 1 ]]; then
+    return 0
+  fi
+  if ! command -v "$GH_BIN" >/dev/null 2>&1; then
+    PR_MERGED_LOOKUP_DISABLED=1
+    return 1
+  fi
+
+  local merged_branches=""
+  merged_branches="$(
+    "$GH_BIN" pr list --state merged --base "$BASE_BRANCH" --limit 200 --json headRefName --jq '.[].headRefName' 2>/dev/null || true
+  )"
+  if [[ -n "$merged_branches" ]]; then
+    while IFS= read -r merged_branch; do
+      [[ -z "$merged_branch" ]] && continue
+      MERGED_PR_BRANCHES["$merged_branch"]=1
+    done <<< "$merged_branches"
+  fi
+  PR_MERGED_LOOKUP_LOADED=1
+  return 0
+}
+
+branch_has_merged_pr() {
+  local branch="$1"
+  if [[ "$INCLUDE_PR_MERGED" -ne 1 ]]; then
+    return 1
+  fi
+  load_merged_pr_branches || return 1
+  [[ -n "${MERGED_PR_BRANCHES[$branch]:-}" ]]
+}
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   echo "[agent-worktree-prune] --base requires a non-empty branch name." >&2
   exit 1
@@ -342,6 +389,7 @@ process_entry() {
   fi
 
   local remove_reason=""
+  local branch_delete_mode="safe"
 
   if [[ -z "$branch_ref" ]]; then
     remove_reason="detached-worktree"
@@ -352,6 +400,9 @@ process_entry() {
       if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
         remove_reason="merged-agent-branch"
       fi
+    elif [[ "$DELETE_BRANCHES" -eq 1 ]] && branch_has_merged_pr "$branch"; then
+      remove_reason="merged-agent-pr"
+      branch_delete_mode="force"
     elif [[ "$ONLY_DIRTY_WORKTREES" -eq 1 ]] && is_clean_worktree "$wt"; then
       remove_reason="clean-agent-worktree"
     fi
@@ -383,13 +434,19 @@ process_entry() {
 
   if git -C "$repo_root" show-ref --verify --quiet "refs/heads/${branch}" && ! branch_has_worktree "$branch"; then
     if [[ "$branch" == agent/* && "$DELETE_BRANCHES" -eq 1 ]]; then
-      if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
+      local delete_flag="-d"
+      local deleted_label="merged"
+      if [[ "$branch_delete_mode" == "force" ]]; then
+        delete_flag="-D"
+        deleted_label="merged PR"
+      fi
+      if run_cmd git -C "$repo_root" branch "$delete_flag" "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
-        echo "[agent-worktree-prune] Deleted merged branch: ${branch}"
+        echo "[agent-worktree-prune] Deleted ${deleted_label} branch: ${branch}"
         if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
           if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
             run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
-            echo "[agent-worktree-prune] Deleted merged remote branch: ${branch}"
+            echo "[agent-worktree-prune] Deleted ${deleted_label} remote branch: ${branch}"
           fi
         fi
       fi
@@ -420,7 +477,7 @@ while IFS= read -r line || [[ -n "$line" ]]; do
       current_branch_ref="${line#branch }"
       ;;
   esac
-done < <(git -C "$repo_root" worktree list --porcelain)
+  done < <(git -C "$repo_root" worktree list --porcelain)
 
 process_entry "$current_wt" "$current_branch_ref"
 
@@ -436,14 +493,27 @@ if [[ "$DELETE_BRANCHES" -eq 1 ]]; then
     if ! branch_idle_gate "$branch" "" "stale-merged-branch"; then
       continue
     fi
+    merged_by_ancestor=0
+    merged_by_pr=0
     if git -C "$repo_root" merge-base --is-ancestor "$branch" "$BASE_BRANCH"; then
-      if run_cmd git -C "$repo_root" branch -d "$branch" >/dev/null 2>&1; then
+      merged_by_ancestor=1
+    elif branch_has_merged_pr "$branch"; then
+      merged_by_pr=1
+    fi
+    if [[ "$merged_by_ancestor" -eq 1 || "$merged_by_pr" -eq 1 ]]; then
+      delete_flag="-d"
+      deleted_label="merged"
+      if [[ "$merged_by_pr" -eq 1 && "$merged_by_ancestor" -eq 0 ]]; then
+        delete_flag="-D"
+        deleted_label="merged PR"
+      fi
+      if run_cmd git -C "$repo_root" branch "$delete_flag" "$branch" >/dev/null 2>&1; then
         removed_branches=$((removed_branches + 1))
-        echo "[agent-worktree-prune] Deleted stale merged branch: ${branch}"
+        echo "[agent-worktree-prune] Deleted stale ${deleted_label} branch: ${branch}"
         if [[ "$DELETE_REMOTE_BRANCHES" -eq 1 ]]; then
           if git -C "$repo_root" ls-remote --exit-code --heads origin "$branch" >/dev/null 2>&1; then
             run_cmd git -C "$repo_root" push origin --delete "$branch" >/dev/null 2>&1 || true
-            echo "[agent-worktree-prune] Deleted stale merged remote branch: ${branch}"
+            echo "[agent-worktree-prune] Deleted stale ${deleted_label} remote branch: ${branch}"
           fi
         fi
       fi