@imdeadpool/guardex 7.0.6 → 7.0.7

package/README.md

@@ -9,6 +9,11 @@ GuardeX is a safety layer for parallel Codex/agent work in git repos.
 > [!WARNING]
 > Not affiliated with OpenAI or Codex. Not an official tool.
 
+## Frontend Repo
+
+- Standalone frontend repository: https://github.com/Webu-PRO/guardex-frontend
+- This repository tracks/mirrors the frontend under `frontend/` as documented below.
+
 ## The problem (what was going wrong)
 
 Multiple Codex agents worked on the same files at the same time.
@@ -21,11 +26,16 @@ GuardeX exists to stop that loop.
 
 ```mermaid
 flowchart LR
-    A[Agent A edits file X] --> C[Conflict / overwrite]
-    B[Agent B edits file X] --> C
-    C --> D[Deleted or lost code]
-    D --> E[Rework and confusion]
-    E --> C
+    A[Agent A edits shared files] --> S[Same target surface]
+    B[Agent B edits shared files] --> S
+    C[Agent C edits shared files] --> S
+    D[Agent D edits shared files] --> S
+    E[Agent E edits shared files] --> S
+    S --> F[Conflict / overwrite churn]
+    F --> G[Deleted or lost code]
+    G --> H[Rework and confusion]
+    H --> I[Regression risk grows]
+    I --> F
 ```
 
 ## What GuardeX enforces
@@ -95,9 +105,9 @@ gx finish --all
 
 ![gx lock and delete guard screenshot](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-lock-guard.svg)
 
-### Real VS Code Source Control layout (exact screenshot)
+### VS Code Source Control layout (agent + OpenSpec files)
 
-![Real VS Code Source Control layout](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-vscode-source-control-exact.png)
+![VS Code Source Control layout with OpenSpec files](https://raw.githubusercontent.com/recodeee/guardex/main/docs/images/workflow-source-control.svg)
 
 ## Copy-paste: common commands
 
@@ -213,6 +223,7 @@ gx agents stop
 - Codex/agent sessions stay blocked on protected branches and must use `agent/*` branch + PR workflow.
 - On protected `main`, `gx doctor` auto-runs in a sandbox agent branch/worktree.
 - In-place agent branching is disabled; `scripts/agent-branch-start.sh` always creates a separate worktree to keep your visible local/base branch unchanged.
+- 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.
 - `scripts/agent-branch-start.sh` hydrates `scripts/codex-agent.sh` into new sandbox worktrees when missing, so auto-finish launcher flow stays available.
 
 ## Configure protected branches
@@ -282,6 +293,34 @@ Then in your repo:
 
 After that, the app reviews new and updated pull requests automatically.
 
+## Frontend mirror sync (`Webu-PRO/guardex-frontend`)
+
+This repo includes `.github/workflows/sync-frontend-mirror.yml`, which mirrors
+the `frontend/` subtree to a separate repository whenever `main` receives
+changes under `frontend/**`.
+
+Default target:
+
+- repo: `Webu-PRO/guardex-frontend`
+- branch: `main`
+
+Required setup (in this repository):
+
+1. `Settings -> Secrets and variables -> Actions`
+2. Add repository secret `GUARDEX_FRONTEND_MIRROR_PAT`
+   - value must be a token with `contents:write` access to `Webu-PRO/guardex-frontend`
+
+Optional overrides (Actions Variables):
+
+- `GUARDEX_FRONTEND_MIRROR_REPO` (default `Webu-PRO/guardex-frontend`)
+- `GUARDEX_FRONTEND_MIRROR_BRANCH` (default `main`)
+
+Manual run:
+
+```sh
+gh workflow run sync-frontend-mirror.yml
+```
+
 ## Companion dependency: `codex-auth` account switcher
 
 For multi-identity Codex workflows, GuardeX pairs with
@@ -373,6 +412,11 @@ npm pack --dry-run
 
 ## Release notes
 
+### v7.0.7
+
+- **Fixed: next publish target now advances past npm.** Bumped `@imdeadpool/guardex` from `7.0.6` to `7.0.7` so the next `npm publish` does not collide with the already-published registry version.
+- **Fixed: root package metadata drift in `package-lock.json`.** The lockfile root version had fallen behind the package manifest (`7.0.4` vs. `7.0.6`), which made release metadata inconsistent. The bump resynchronized `package.json` and `package-lock.json` on `7.0.7`.
+
 ### v7.0.6
 
 - **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 made it report "changed 1 package" without actually overwriting the files (a known quirk triggered when the user just bumped from 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 still stale. `gx` now re-reads the globally installed `package.json` after the `@latest` install returns, compares its `version` field to the advertised latest, and if they don't match runs a pinned retry `npm i -g @imdeadpool/guardex@<latest>` to force the cache past the obstructing entry. If the pinned retry also fails to advance the on-disk version, the user gets a clear hint (`npm root -g && npm cache verify`) instead of a silent loop.

package/bin/multiagent-safety.js

@@ -35,6 +35,7 @@ const SCORECARD_BIN = process.env.GUARDEX_SCORECARD_BIN || 'scorecard';
 const GIT_PROTECTED_BRANCHES_KEY = 'multiagent.protectedBranches';
 const GIT_BASE_BRANCH_KEY = 'multiagent.baseBranch';
 const GIT_SYNC_STRATEGY_KEY = 'multiagent.sync.strategy';
+const GUARDEX_REPO_TOGGLE_ENV = 'GUARDEX_ON';
 const DEFAULT_PROTECTED_BRANCHES = ['dev', 'main', 'master'];
 const DEFAULT_BASE_BRANCH = 'dev';
 const DEFAULT_SYNC_STRATEGY = 'rebase';
@@ -49,6 +50,7 @@ const TEMPLATE_FILES = [
   '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',
@@ -68,6 +70,7 @@ const REQUIRED_WORKFLOW_FILES = [
   'scripts/agent-branch-finish.sh',
   'scripts/agent-worktree-prune.sh',
   'scripts/agent-file-locks.py',
+  'scripts/guardex-env.sh',
   'scripts/install-agent-git-hooks.sh',
   '.githooks/pre-commit',
   '.githooks/post-merge',
@@ -113,6 +116,7 @@ const CRITICAL_GUARDRAIL_PATHS = new Set([
   'scripts/agent-worktree-prune.sh',
   'scripts/codex-agent.sh',
   'scripts/agent-file-locks.py',
+  'scripts/guardex-env.sh',
 ]);
 
 const LOCK_FILE_RELATIVE = '.omx/state/agent-file-locks.json';
@@ -130,6 +134,7 @@ const MANAGED_GITIGNORE_PATHS = [
   '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',
@@ -289,6 +294,9 @@ function statusDot(status) {
   if (status === 'inactive') {
     return colorize('●', '31'); // red
   }
+  if (status === 'disabled') {
+    return colorize('●', '36'); // cyan
+  }
   return colorize('●', '33'); // yellow for degraded/unknown
 }
 
@@ -754,7 +762,6 @@ function ensurePackageScripts(repoRoot, dryRun, options = {}) {
 }
 
 function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
-  const force = Boolean(options.force);
   const agentsPath = path.join(repoRoot, 'AGENTS.md');
   const snippet = fs.readFileSync(path.join(TEMPLATE_ROOT, 'AGENTS.multiagent-safety.md'), 'utf8').trimEnd();
   const managedRegex = new RegExp(
@@ -771,9 +778,6 @@ function ensureAgentsSnippet(repoRoot, dryRun, options = {}) {
 
   const existing = fs.readFileSync(agentsPath, 'utf8');
   if (managedRegex.test(existing)) {
-    if (!force) {
-      return { status: 'unchanged', file: 'AGENTS.md', note: 'preserved existing guardex-managed block' };
-    }
     const next = existing.replace(managedRegex, snippet);
     if (next === existing) {
       return { status: 'unchanged', file: 'AGENTS.md' };
@@ -3155,6 +3159,75 @@ function parseAutoApproval(name) {
   return null;
 }
 
+function parseBooleanLike(raw) {
+  if (raw == null) return null;
+  const normalized = String(raw).trim().toLowerCase();
+  if (!normalized) return null;
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return null;
+}
+
+function parseDotenvAssignmentValue(raw) {
+  let value = String(raw || '').trim();
+  if (!value) return '';
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) {
+    return value.slice(1, -1).trim();
+  }
+  value = value.replace(/\s+#.*$/, '').trim();
+  return value;
+}
+
+function readRepoDotenvValue(repoRoot, name) {
+  const envPath = path.join(repoRoot, '.env');
+  if (!fs.existsSync(envPath)) return null;
+  const pattern = new RegExp(`^\\s*(?:export\\s+)?${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*=\\s*(.*)$`);
+  const lines = fs.readFileSync(envPath, 'utf8').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = line.match(pattern);
+    if (!match) continue;
+    return parseDotenvAssignmentValue(match[1]);
+  }
+  return null;
+}
+
+function resolveGuardexRepoToggle(repoRoot, env = process.env) {
+  const envRaw = env[GUARDEX_REPO_TOGGLE_ENV];
+  const envEnabled = parseBooleanLike(envRaw);
+  if (envEnabled !== null) {
+    return {
+      enabled: envEnabled,
+      source: 'process environment',
+      raw: String(envRaw).trim(),
+    };
+  }
+
+  const dotenvRaw = readRepoDotenvValue(repoRoot, GUARDEX_REPO_TOGGLE_ENV);
+  const dotenvEnabled = parseBooleanLike(dotenvRaw);
+  if (dotenvEnabled !== null) {
+    return {
+      enabled: dotenvEnabled,
+      source: 'repo .env',
+      raw: String(dotenvRaw).trim(),
+    };
+  }
+
+  return {
+    enabled: true,
+    source: 'default',
+    raw: '',
+  };
+}
+
+function describeGuardexRepoToggle(toggle) {
+  if (!toggle || toggle.source === 'default') {
+    return 'default enabled mode';
+  }
+  return `${toggle.source} (${GUARDEX_REPO_TOGGLE_ENV}=${toggle.raw})`;
+}
+
 function parseVersionString(version) {
   const match = String(version || '').trim().match(/^v?(\d+)\.(\d+)\.(\d+)/);
   if (!match) return null;
@@ -3605,6 +3678,22 @@ function findStaleLockPaths(repoRoot, locks) {
 
 function runInstallInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
+  const guardexToggle = resolveGuardexRepoToggle(repoRoot);
+  if (!guardexToggle.enabled) {
+    return {
+      repoRoot,
+      operations: [
+        {
+          status: 'skipped',
+          file: '.env',
+          note: `Guardex disabled by ${describeGuardexRepoToggle(guardexToggle)}`,
+        },
+      ],
+      hookResult: { status: 'skipped', key: 'core.hooksPath', value: '(unchanged)' },
+      guardexEnabled: false,
+      guardexToggle,
+    };
+  }
   const operations = [];
 
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
@@ -3628,11 +3717,27 @@ function runInstallInternal(options) {
 
   const hookResult = configureHooks(repoRoot, Boolean(options.dryRun));
 
-  return { repoRoot, operations, hookResult };
+  return { repoRoot, operations, hookResult, guardexEnabled: true, guardexToggle };
 }
 
 function runFixInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
+  const guardexToggle = resolveGuardexRepoToggle(repoRoot);
+  if (!guardexToggle.enabled) {
+    return {
+      repoRoot,
+      operations: [
+        {
+          status: 'skipped',
+          file: '.env',
+          note: `Guardex disabled by ${describeGuardexRepoToggle(guardexToggle)}`,
+        },
+      ],
+      hookResult: { status: 'skipped', key: 'core.hooksPath', value: '(unchanged)' },
+      guardexEnabled: false,
+      guardexToggle,
+    };
+  }
   const operations = [];
 
   operations.push(...ensureOmxScaffold(repoRoot, Boolean(options.dryRun)));
@@ -3682,11 +3787,25 @@ function runFixInternal(options) {
 
   const hookResult = configureHooks(repoRoot, Boolean(options.dryRun));
 
-  return { repoRoot, operations, hookResult };
+  return { repoRoot, operations, hookResult, guardexEnabled: true, guardexToggle };
 }
 
 function runScanInternal(options) {
   const repoRoot = resolveRepoRoot(options.target);
+  const guardexToggle = resolveGuardexRepoToggle(repoRoot);
+  const currentBranchResult = gitRun(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFailure: true });
+  const branch = currentBranchResult.status === 0 ? currentBranchResult.stdout.trim() : '(unknown)';
+  if (!guardexToggle.enabled) {
+    return {
+      repoRoot,
+      branch,
+      findings: [],
+      errors: 0,
+      warnings: 0,
+      guardexEnabled: false,
+      guardexToggle,
+    };
+  }
   const findings = [];
 
   const requiredPaths = [
@@ -3777,15 +3896,14 @@ function runScanInternal(options) {
   const errors = findings.filter((item) => item.level === 'error');
   const warnings = findings.filter((item) => item.level === 'warn');
 
-  const currentBranchResult = gitRun(repoRoot, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFailure: true });
-  const branch = currentBranchResult.status === 0 ? currentBranchResult.stdout.trim() : '(unknown)';
-
   return {
     repoRoot,
     branch,
     findings,
     errors: errors.length,
     warnings: warnings.length,
+    guardexEnabled: true,
+    guardexToggle,
   };
 }
 
@@ -3811,6 +3929,8 @@ function printScanResult(scan, json = false) {
         {
           repoRoot: scan.repoRoot,
           branch: scan.branch,
+          guardexEnabled: scan.guardexEnabled !== false,
+          guardexToggle: scan.guardexToggle || null,
           errors: scan.errors,
           warnings: scan.warnings,
           findings: scan.findings,
@@ -3825,6 +3945,13 @@ function printScanResult(scan, json = false) {
   console.log(`[${TOOL_NAME}] Scan target: ${scan.repoRoot}`);
   console.log(`[${TOOL_NAME}] Branch: ${scan.branch}`);
 
+  if (scan.guardexEnabled === false) {
+    console.log(
+      `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(scan.guardexToggle)}).`,
+    );
+    return;
+  }
+
   if (scan.findings.length === 0) {
     console.log(`[${TOOL_NAME}] ✅ No safety issues detected.`);
     return;
@@ -3838,6 +3965,10 @@ function printScanResult(scan, json = false) {
 }
 
 function setExitCodeFromScan(scan) {
+  if (scan.guardexEnabled === false) {
+    process.exitCode = 0;
+    return;
+  }
   if (scan.errors > 0) {
     process.exitCode = 2;
     return;
@@ -3879,7 +4010,9 @@ function status(rawArgs) {
   const inGitRepo = isGitRepo(targetPath);
   const scanResult = inGitRepo ? runScanInternal({ target: targetPath, json: false }) : null;
   const repoServiceStatus = scanResult
-    ? (scanResult.errors === 0 && scanResult.warnings === 0 ? 'active' : 'degraded')
+    ? (scanResult.guardexEnabled === false
+      ? 'disabled'
+      : (scanResult.errors === 0 && scanResult.warnings === 0 ? 'active' : 'degraded'))
     : 'inactive';
 
   const payload = {
@@ -3893,6 +4026,8 @@ function status(rawArgs) {
       target: targetPath,
       inGitRepo,
       serviceStatus: repoServiceStatus,
+      guardexEnabled: scanResult ? scanResult.guardexEnabled !== false : null,
+      guardexToggle: scanResult ? scanResult.guardexToggle || null : null,
       scan: scanResult
         ? {
           repoRoot: scanResult.repoRoot,
@@ -3942,6 +4077,17 @@ function status(rawArgs) {
     return;
   }
 
+  if (scanResult.guardexEnabled === false) {
+    console.log(
+      `[${TOOL_NAME}] Repo safety service: ${statusDot('disabled')} disabled (${describeGuardexRepoToggle(scanResult.guardexToggle)}).`,
+    );
+    console.log(`[${TOOL_NAME}] Repo: ${scanResult.repoRoot}`);
+    console.log(`[${TOOL_NAME}] Branch: ${scanResult.branch}`);
+    printToolLogsSummary();
+    process.exitCode = 0;
+    return;
+  }
+
   if (scanResult.errors === 0 && scanResult.warnings === 0) {
     console.log(`[${TOOL_NAME}] Repo safety service: ${statusDot('active')} active.`);
   } else if (scanResult.errors === 0) {
@@ -3983,6 +4129,13 @@ function install(rawArgs) {
   printOperations('Install target', payload, options.dryRun);
 
   if (!options.dryRun) {
+    if (payload.guardexEnabled === false) {
+      console.log(
+        `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(payload.guardexToggle)}). Skipping repo bootstrap.`,
+      );
+      process.exitCode = 0;
+      return;
+    }
     if (!options.skipAgents) {
       console.log(`[${TOOL_NAME}] AGENTS.md managed policy block is configured by install.`);
     }
@@ -4008,6 +4161,13 @@ function fix(rawArgs) {
   printOperations('Fix target', payload, options.dryRun);
 
   if (!options.dryRun) {
+    if (payload.guardexEnabled === false) {
+      console.log(
+        `[${TOOL_NAME}] Guardex is disabled for this repo (${describeGuardexRepoToggle(payload.guardexToggle)}). Skipping repo repair.`,
+      );
+      process.exitCode = 0;
+      return;
+    }
     console.log(`[${TOOL_NAME}] Repair complete. Next step: ${TOOL_NAME} scan`);
   }
 
@@ -4047,11 +4207,20 @@ function doctor(rawArgs) {
   const fixPayload = runFixInternal(options);
   const scanResult = runScanInternal({ target: options.target, json: false });
   const currentBaseBranch = currentBranchName(scanResult.repoRoot);
-  const autoFinishSummary = autoFinishReadyAgentBranches(scanResult.repoRoot, {
-    baseBranch: currentBaseBranch,
-    dryRun: options.dryRun,
-  });
-  const safe = scanResult.errors === 0 && scanResult.warnings === 0;
+  const autoFinishSummary = scanResult.guardexEnabled === false
+    ? {
+      enabled: false,
+      attempted: 0,
+      completed: 0,
+      skipped: 0,
+      failed: 0,
+      details: [],
+    }
+    : autoFinishReadyAgentBranches(scanResult.repoRoot, {
+      baseBranch: currentBaseBranch,
+      dryRun: options.dryRun,
+    });
+  const safe = scanResult.guardexEnabled === false || (scanResult.errors === 0 && scanResult.warnings === 0);
   const musafe = safe;
 
   if (options.json) {
@@ -4068,6 +4237,8 @@ function doctor(rawArgs) {
             dryRun: Boolean(options.dryRun),
           },
           scan: {
+            guardexEnabled: scanResult.guardexEnabled !== false,
+            guardexToggle: scanResult.guardexToggle || null,
             errors: scanResult.errors,
             warnings: scanResult.warnings,
             findings: scanResult.findings,
@@ -4084,6 +4255,11 @@ function doctor(rawArgs) {
 
   printOperations('Doctor/fix', fixPayload, options.dryRun);
   printScanResult(scanResult, false);
+  if (scanResult.guardexEnabled === false) {
+    console.log(`[${TOOL_NAME}] Repo-local Guardex enforcement is intentionally disabled.`);
+    setExitCodeFromScan(scanResult);
+    return;
+  }
   if (autoFinishSummary.enabled) {
     console.log(
       `[${TOOL_NAME}] Auto-finish sweep (base=${currentBaseBranch}): attempted=${autoFinishSummary.attempted}, completed=${autoFinishSummary.completed}, skipped=${autoFinishSummary.skipped}, failed=${autoFinishSummary.failed}`,
@@ -4825,6 +5001,7 @@ function initWorkspace(rawArgs) {
 function doctorAudit(rawArgs) {
   const options = parseDoctorArgs(rawArgs);
   const repoRoot = resolveRepoRoot(options.target);
+  const guardexToggle = resolveGuardexRepoToggle(repoRoot);
   const failures = [];
   const warnings = [];
 
@@ -4841,6 +5018,13 @@ function doctorAudit(rawArgs) {
   }
 
   console.log(`[multiagent-safety] doctor target: ${repoRoot}`);
+  if (!guardexToggle.enabled) {
+    console.log(
+      `[multiagent-safety] Guardex is disabled for this repo (${describeGuardexRepoToggle(guardexToggle)}).`,
+    );
+    console.log('[multiagent-safety] doctor passed.');
+    return;
+  }
 
   const hooksPath = run('git', ['-C', repoRoot, 'config', '--get', 'core.hooksPath']);
   if (hooksPath.status !== 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.6",
+  "version": "7.0.7",
   "description": "GuardeX: the Guardian T-Rex for your repo, with hardened multi-agent git guardrails.",
   "license": "MIT",
   "preferGlobal": true,
@@ -58,7 +58,7 @@
   "bugs": {
     "url": "https://github.com/recodeee/guardex/issues"
   },
-  "homepage": "https://github.com/recodeee/guardex#readme",
+  "homepage": "https://guardextutorial.com",
   "funding": "https://github.com/sponsors/recodeecom",
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.multiagent-safety.md

@@ -1,6 +1,8 @@
 <!-- multiagent-safety:START -->
 ## Multi-Agent Safety Contract
 
+**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.** 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`.
 
 **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.
@@ -13,7 +15,7 @@
 
 **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. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+**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/githooks/post-checkout

@@ -9,6 +9,19 @@ if [[ "${GUARDEX_ALLOW_PRIMARY_BRANCH_SWITCH:-0}" == "1" ]]; then
   exit 0
 fi
 
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$repo_root" ]]; then
+  exit 0
+fi
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  exit 0
+fi
+
 # Skip in secondary worktrees — only the primary checkout is guarded.
 git_dir_abs="$(cd "$(git rev-parse --git-dir)" && pwd -P)"
 common_dir_abs="$(cd "$(git rev-parse --git-common-dir)" && pwd -P)"

package/templates/githooks/post-merge

@@ -9,6 +9,14 @@ repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 if [[ -z "$repo_root" ]]; then
   exit 0
 fi
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  exit 0
+fi
 
 branch="$(git -C "$repo_root" rev-parse --abbrev-ref HEAD 2>/dev/null || true)"
 if [[ -z "$branch" || "$branch" == "HEAD" ]]; then

package/templates/githooks/pre-commit

@@ -9,6 +9,19 @@ if [[ -z "$branch" ]]; then
   exit 0
 fi
 
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$repo_root" ]]; then
+  exit 0
+fi
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  exit 0
+fi
+
 if [[ "${ALLOW_COMMIT_ON_PROTECTED_BRANCH:-0}" == "1" ]]; then
   exit 0
 fi

package/templates/githooks/pre-push

@@ -5,6 +5,19 @@ if [[ "${ALLOW_PUSH_ON_PROTECTED_BRANCH:-0}" == "1" || "${ALLOW_COMMIT_ON_PROTEC
   exit 0
 fi
 
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$repo_root" ]]; then
+  exit 0
+fi
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  exit 0
+fi
+
 is_vscode_git_context=0
 if [[ -n "${VSCODE_GIT_IPC_HANDLE:-}" || -n "${VSCODE_GIT_ASKPASS_NODE:-}" || -n "${VSCODE_IPC_HOOK_CLI:-}" ]]; then
   is_vscode_git_context=1

package/templates/scripts/agent-branch-start.sh

@@ -389,6 +389,23 @@ fi
 
 repo_root="$(git rev-parse --show-toplevel)"
 
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  toggle_source="$(guardex_repo_toggle_source "$repo_root" || true)"
+  toggle_raw="$(guardex_repo_toggle_raw "$repo_root" || true)"
+  if [[ -n "$toggle_source" && -n "$toggle_raw" ]]; then
+    echo "[agent-branch-start] Guardex is disabled for this repo (${toggle_source}: GUARDEX_ON=${toggle_raw})." >&2
+  else
+    echo "[agent-branch-start] Guardex is disabled for this repo." >&2
+  fi
+  echo "[agent-branch-start] Skip Guardex worktree/OpenSpec flow or re-enable with GUARDEX_ON=1." >&2
+  exit 1
+fi
+
 if [[ "$BASE_BRANCH_EXPLICIT" -eq 1 && -z "$BASE_BRANCH" ]]; then
   echo "[agent-branch-start] --base requires a non-empty branch name." >&2
   exit 1
@@ -474,12 +491,14 @@ if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]] && is_protected_bra
   fi
 fi
 
-git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref"
-git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
-
-if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${BASE_BRANCH}"; then
-  git -C "$worktree_path" branch --set-upstream-to="origin/${BASE_BRANCH}" "$branch_name" >/dev/null 2>&1 || true
+worktree_add_output=""
+if ! worktree_add_output="$(git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref" 2>&1)"; then
+  printf '%s\n' "$worktree_add_output" >&2
+  exit 1
 fi
+git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$BASE_BRANCH" >/dev/null 2>&1 || true
+# Fresh agent branches should start unpublished; clear any inherited base-branch tracking.
+git -C "$worktree_path" branch --unset-upstream "$branch_name" >/dev/null 2>&1 || true
 
 if [[ -n "$auto_transfer_stash_ref" ]]; then
   if git -C "$worktree_path" stash apply "$auto_transfer_stash_ref" >/dev/null 2>&1; then

package/templates/scripts/codex-agent.sh

@@ -130,6 +130,23 @@ if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
 fi
 repo_root="$(git rev-parse --show-toplevel)"
 
+guardex_env_helper="${repo_root}/scripts/guardex-env.sh"
+if [[ -f "$guardex_env_helper" ]]; then
+  # shellcheck source=/dev/null
+  source "$guardex_env_helper"
+fi
+if declare -F guardex_repo_is_enabled >/dev/null 2>&1 && ! guardex_repo_is_enabled "$repo_root"; then
+  toggle_source="$(guardex_repo_toggle_source "$repo_root" || true)"
+  toggle_raw="$(guardex_repo_toggle_raw "$repo_root" || true)"
+  if [[ -n "$toggle_source" && -n "$toggle_raw" ]]; then
+    echo "[codex-agent] Guardex is disabled for this repo (${toggle_source}: GUARDEX_ON=${toggle_raw})." >&2
+  else
+    echo "[codex-agent] Guardex is disabled for this repo." >&2
+  fi
+  echo "[codex-agent] Skip Guardex sandbox flow or re-enable with GUARDEX_ON=1." >&2
+  exit 1
+fi
+
 sanitize_slug() {
   local raw="$1"
   local fallback="${2:-task}"
@@ -274,11 +291,13 @@ start_sandbox_fallback() {
     return 1
   fi
 
-  git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref" >/dev/null
-  git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$base_branch" >/dev/null 2>&1 || true
-  if git -C "$repo_root" show-ref --verify --quiet "refs/remotes/origin/${base_branch}"; then
-    git -C "$worktree_path" branch --set-upstream-to="origin/${base_branch}" "$branch_name" >/dev/null 2>&1 || true
+  local worktree_add_output=""
+  if ! worktree_add_output="$(git -C "$repo_root" worktree add -b "$branch_name" "$worktree_path" "$start_ref" 2>&1)"; then
+    printf '%s\n' "$worktree_add_output" >&2
+    return 1
   fi
+  git -C "$repo_root" config "branch.${branch_name}.guardexBase" "$base_branch" >/dev/null 2>&1 || true
+  git -C "$worktree_path" branch --unset-upstream "$branch_name" >/dev/null 2>&1 || true
 
   printf '[agent-branch-start] Created branch: %s\n' "$branch_name"
   printf '[agent-branch-start] Worktree: %s\n' "$worktree_path"

package/templates/scripts/guardex-env.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+
+guardex_normalize_bool() {
+  local raw="${1:-}"
+  local fallback="${2:-}"
+  local lowered
+  lowered="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$lowered" in
+    1|true|yes|on) printf '1' ;;
+    0|false|no|off) printf '0' ;;
+    '') printf '%s' "$fallback" ;;
+    *) printf '%s' "$fallback" ;;
+  esac
+}
+
+guardex_read_repo_dotenv_var() {
+  local repo_root="$1"
+  local key="${2:-GUARDEX_ON}"
+  local env_file="${repo_root}/.env"
+  local line value
+
+  [[ -f "$env_file" ]] || return 1
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ "$line" =~ ^[[:space:]]*# ]] && continue
+    if [[ "$line" =~ ^[[:space:]]*(export[[:space:]]+)?${key}[[:space:]]*=(.*)$ ]]; then
+      value="${BASH_REMATCH[2]}"
+      value="$(printf '%s' "$value" | sed -E 's/[[:space:]]+#.*$//; s/^[[:space:]]+//; s/[[:space:]]+$//')"
+      if [[ "$value" == \"*\" && "$value" == *\" ]]; then
+        value="${value:1:${#value}-2}"
+      elif [[ "$value" == \'*\' && "$value" == *\' ]]; then
+        value="${value:1:${#value}-2}"
+      fi
+      printf '%s' "$value"
+      return 0
+    fi
+  done < "$env_file"
+
+  return 1
+}
+
+guardex_repo_toggle_raw() {
+  local repo_root="$1"
+  if [[ -n "${GUARDEX_ON:-}" ]]; then
+    printf '%s' "$GUARDEX_ON"
+    return 0
+  fi
+  guardex_read_repo_dotenv_var "$repo_root" "GUARDEX_ON"
+}
+
+guardex_repo_toggle_source() {
+  local repo_root="$1"
+  if [[ -n "${GUARDEX_ON:-}" ]]; then
+    printf 'process environment'
+    return 0
+  fi
+  if guardex_read_repo_dotenv_var "$repo_root" "GUARDEX_ON" >/dev/null; then
+    printf 'repo .env'
+    return 0
+  fi
+  return 1
+}
+
+guardex_repo_is_enabled() {
+  local repo_root="$1"
+  local raw normalized
+  if raw="$(guardex_repo_toggle_raw "$repo_root")"; then
+    normalized="$(guardex_normalize_bool "$raw" "")"
+    if [[ "$normalized" == "0" ]]; then
+      return 1
+    fi
+  fi
+  return 0
+}

package/templates/scripts/openspec/init-change-workspace.sh

@@ -66,6 +66,12 @@ if [[ ! -f "${CHANGE_DIR}/tasks.md" ]]; then
 - [ ] 3.1 Run targeted project verification commands.
 - [ ] 3.2 Run \`openspec validate ${CHANGE_SLUG} --type change --strict\`.
 - [ ] 3.3 Run \`openspec validate --specs\`.
+
+## 4. Completion
+
+- [ ] 4.1 Finish the agent branch via PR merge + cleanup (\`gx finish --via-pr --wait-for-merge --cleanup\` or \`bash scripts/agent-branch-finish.sh --branch <agent-branch> --base <base-branch> --via-pr --wait-for-merge --cleanup\`).
+- [ ] 4.2 Record PR URL + final \`MERGED\` state in the completion handoff.
+- [ ] 4.3 Confirm sandbox cleanup (\`git worktree list\`, \`git branch -a\`) or capture a \`BLOCKED:\` handoff if merge/cleanup is pending.
 TASKSEOF
 fi