@imdeadpool/guardex 7.0.43 → 7.1.0

package/README.md

@@ -308,6 +308,32 @@ Being honest about where this still has issues:
 <details open>
 <summary><strong>v7.x</strong></summary>
 
+### v7.0.43
+- Budget-friendly CI defaults for gitguardex-managed projects: live
+  workflows drop `push: main`, gate per-PR jobs on `pull_request.draft
+  == false`, add `concurrency: cancel-in-progress`, and split per-runtime
+  matrix coverage into a weekly `ci-full.yml`. CodeQL and Scorecard run
+  on the weekly schedule + `workflow_dispatch` only. Templates under
+  `templates/github/workflows/` carry the same posture so downstream
+  projects inherit it via `gx setup`.
+- New `gx ci-init` subcommand scaffolds `ci.yml`, `ci-full.yml`, `cr.yml`,
+  and a `README.md` budget-posture guide into a target repo's
+  `.github/workflows/` directory. Supports `--target`, `--dry-run`,
+  `--force`, `--no-stage`, and `--json`.
+- New `gx budget` subcommand wraps the new GitHub
+  `/settings/billing/usage` endpoint (the legacy
+  `/settings/billing/actions` endpoint was retired in early 2026) and
+  reports monthly Actions minute spend with warn/critical USD thresholds
+  per `--org` or `--user`.
+- Per-PR label opt-in for `agent/*` lanes: `needs-review` runs AI code
+  review on an otherwise-skipped agent PR; `needs-ci-full` triggers the
+  full cross-runtime matrix without waiting for the weekly schedule.
+- `gx branch finish` runs `scripts/agent-preflight.sh` in the worktree
+  before pushing. Default script auto-detects pnpm/npm, Rust, and Python
+  stacks and refuses the push on verification failure. After pre-flight
+  passes, draft PRs are promoted to ready-for-review so the
+  budget-friendly CI defaults fire once on a known-passing commit.
+
 ### v7.0.42
 - Bumped `@imdeadpool/guardex` from `7.0.41` to `7.0.42` so the current
   `main` payload can publish under a fresh npm version after `7.0.41` reached

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imdeadpool/guardex",
-  "version": "7.0.43",
+  "version": "7.1.0",
   "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,
@@ -18,6 +18,7 @@
     "agent:branch:merge": "bash ./scripts/agent-branch-merge.sh",
     "agent:cleanup": "gx cleanup",
     "agent:hooks:install": "bash ./scripts/install-agent-git-hooks.sh",
+    "guardex:install-global": "bash ./scripts/install-global-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",

package/skills/gx-act/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gx-act
+description: "Run GitHub Actions workflows locally with nektos/act before pushing, so CI failures are caught on the laptop and the PR can be squash-merged on the first remote run."
+---
+
+# gx-act — local GitHub Actions
+
+Use whenever a change touches code that would trigger CI on GitHub. Run the workflows locally with `act` first; only push the branch when the local run is green, then squash-merge the PR on GitHub.
+
+## When to invoke
+
+- Before `gx pr open` / `gx pr sync` / `gx branch finish --via-pr`.
+- Before re-pushing after a CI failure.
+- When iterating on `.github/workflows/*.yml` itself.
+
+## Install `act`
+
+`act` requires Docker (or Podman). Check the binary:
+
+```sh
+command -v act || echo "act not installed"
+```
+
+Install one way:
+
+```sh
+# Linux/macOS via the upstream installer
+curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash -s -- -b "$HOME/.local/bin"
+
+# macOS via Homebrew
+brew install act
+
+# Arch
+sudo pacman -S act
+
+# Or use the GitHub CLI extension
+gh extension install https://github.com/nektos/gh-act
+```
+
+Upstream: https://github.com/nektos/act
+
+## Quick commands
+
+```sh
+# List jobs the local runner would execute for the push event
+act -l
+
+# Run the default push workflows (what GitHub runs on a normal push)
+act push
+
+# Run a specific event
+act pull_request
+act workflow_dispatch -W .github/workflows/release.yml
+
+# Run a single job
+act -j test
+
+# Pin a runner image (medium is the act default; large matches real GH closer)
+act -P ubuntu-latest=catthehacker/ubuntu:act-latest
+
+# Pass secrets / env without committing them
+act -s GITHUB_TOKEN="$GITHUB_TOKEN" --env-file .env.act
+
+# Reuse containers between runs (faster iteration)
+act --reuse
+```
+
+## Workflow (local CI → squash-merge on GitHub)
+
+1. Implement the change in the agent worktree.
+2. `act -l` to confirm which jobs will fire for the event you care about.
+3. `act push` (or the specific event/job) until it is green locally.
+4. `gx branch finish --branch "<agent-branch>" --base main --via-pr --wait-for-merge --cleanup`.
+   - Or `gx pr open` then `gx pr sync --auto-merge --merge-strategy squash` for explicit PR control.
+5. On GitHub: squash-merge once the remote run mirrors the local one.
+
+## Notes
+
+- `act` does not reproduce GitHub-hosted services exactly (no real secrets, different runner image, no concurrency groups). Treat a green `act` run as a strong signal, not a proof — the remote run is still authoritative.
+- Keep `act` config in `.actrc` at the repo root so every agent uses the same runner image.
+- If a workflow uses `GITHUB_TOKEN` for API calls, pass a PAT via `-s GITHUB_TOKEN=...`; do not commit it.
+- Add `.actrc`, `.cache/act`, and any `act`-specific event payloads to `.gitignore` if they appear.

package/src/agents/inspect.js

@@ -45,10 +45,22 @@ function parseWorktreeList(outputText) {
   return worktrees;
 }
 
-function worktreePathForBranch(repoRoot, branch) {
+function listWorktrees(repoRoot) {
   const result = git(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
-  if (result.status !== 0) return { worktreePath: repoRoot, worktreeFound: false };
-  const match = parseWorktreeList(result.stdout).find((entry) => entry.branch === branch);
+  return result.status === 0 ? parseWorktreeList(result.stdout) : null;
+}
+
+// `worktrees` (pre-parsed via listWorktrees) lets callers iterating many branches
+// in one pass hoist the invariant `git worktree list` out of their loop. When
+// omitted, the list is fetched on demand — unchanged behavior.
+function worktreePathForBranch(repoRoot, branch, worktrees = null) {
+  let entries = worktrees;
+  if (entries == null) {
+    const result = git(repoRoot, ['worktree', 'list', '--porcelain'], { allowFailure: true });
+    if (result.status !== 0) return { worktreePath: repoRoot, worktreeFound: false };
+    entries = parseWorktreeList(result.stdout);
+  }
+  const match = entries.find((entry) => entry.branch === branch);
   return {
     worktreePath: match?.path || repoRoot,
     worktreeFound: Boolean(match?.path),
@@ -119,7 +131,7 @@ function inspectAgentBranch(options) {
 
   const baseBranch = resolveBaseBranch(repoRoot, branch);
   const compareRef = compareRefForBase(repoRoot, baseBranch);
-  const { worktreePath, worktreeFound } = worktreePathForBranch(repoRoot, branch);
+  const { worktreePath, worktreeFound } = worktreePathForBranch(repoRoot, branch, options.worktrees);
   return { repoRoot, branch, baseBranch, compareRef, worktreePath, worktreeFound };
 }
 
@@ -179,6 +191,7 @@ module.exports = {
   branchLocks,
   changedFiles,
   inspectAgentBranch,
+  listWorktrees,
   parseWorktreeList,
   readLockRegistry,
   renderDiff,

package/src/agents/launch.js

@@ -185,6 +185,14 @@ function buildPromptCommand(parts, agent, prompt) {
   return commandToShell([...parts, prompt]);
 }
 
+function buildResourceEnv() {
+  const cpus = require('node:os').cpus().length || 8;
+  // Cap each agent's cargo parallelism to avoid overwhelming the system
+  // when multiple agents build concurrently.
+  const jobs = Math.max(2, Math.floor(cpus / 4));
+  return [`CARGO_BUILD_JOBS=${jobs}`];
+}
+
 function buildAgentLaunchCommand(options) {
   if (!options || typeof options !== 'object') {
     throw new TypeError('options are required');
@@ -207,7 +215,8 @@ function buildAgentLaunchCommand(options) {
   }
 
   const launchCommand = buildPromptCommand(baseParts, agent, prompt);
-  const envPrefix = buildSessionEnv(agent, sessionId).join(' ');
+  const envParts = [...buildResourceEnv(), ...buildSessionEnv(agent, sessionId)];
+  const envPrefix = envParts.join(' ');
   const launchWithEnv = envPrefix ? `${envPrefix} ${launchCommand}` : launchCommand;
   if (!worktreePath) return launchWithEnv;
   return `cd ${shellQuote(worktreePath)} && ${launchWithEnv}`;

package/src/agents/status.js

@@ -1,5 +1,5 @@
 const { fs, path, LOCK_FILE_RELATIVE, TOOL_NAME } = require('../context');
-const { changedFiles } = require('./inspect');
+const { changedFiles, listWorktrees } = require('./inspect');
 const { listAgentSessions } = require('./sessions');
 
 function uniqueSorted(values) {
@@ -35,10 +35,10 @@ function readLockDetails(repoRoot) {
   return { counts, files };
 }
 
-function readChangedFiles(repoRoot, branch) {
+function readChangedFiles(repoRoot, branch, worktrees) {
   if (!branch) return [];
   try {
-    return changedFiles({ target: repoRoot, branch }).files || [];
+    return changedFiles({ target: repoRoot, branch, worktrees }).files || [];
   } catch (_error) {
     return [];
   }
@@ -53,7 +53,7 @@ function normalizePr(session) {
   };
 }
 
-function normalizeSessionForStatus(session, lockDetails, repoRoot) {
+function normalizeSessionForStatus(session, lockDetails, repoRoot, worktrees) {
   const branch = session.branch || '';
   const worktreePath = session.worktreePath || '';
   const claimedFiles = uniqueSorted([
@@ -73,7 +73,7 @@ function normalizeSessionForStatus(session, lockDetails, repoRoot) {
     worktreeExists: worktreePath ? fs.existsSync(worktreePath) : false,
     lockCount: lockDetails.counts.get(branch) || 0,
     claimedFiles,
-    changedFiles: readChangedFiles(repoRoot, branch),
+    changedFiles: readChangedFiles(repoRoot, branch, worktrees),
     metadata: session.metadata && typeof session.metadata === 'object' ? session.metadata : {},
     launchCommand: session.launchCommand || '',
     tmux: session.tmux && typeof session.tmux === 'object' ? session.tmux : null,
@@ -85,10 +85,13 @@ function normalizeSessionForStatus(session, lockDetails, repoRoot) {
 
 function buildAgentsStatusPayload(repoRoot) {
   const lockDetails = readLockDetails(repoRoot);
+  // Hoist the invariant `git worktree list` out of the per-session loop: fetch it
+  // once here instead of once inside every session's changedFiles() (~6N -> ~6+N).
+  const worktrees = listWorktrees(repoRoot);
   return {
     schemaVersion: 1,
     repoRoot,
-    sessions: listAgentSessions(repoRoot).map((session) => normalizeSessionForStatus(session, lockDetails, repoRoot)),
+    sessions: listAgentSessions(repoRoot).map((session) => normalizeSessionForStatus(session, lockDetails, repoRoot, worktrees)),
   };
 }
 

package/src/budget/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const cp = require('node:child_process');
+const { GH_BIN } = require('../context');
 
 const TOOL_NAME = 'gx';
 
@@ -8,7 +9,7 @@ const DEFAULT_WARN_NET_USD = 1; // any paid spend at all
 const DEFAULT_CRITICAL_NET_USD = 10; // paid spend that has caused merge blocks before
 
 function runGh(args) {
-  const result = cp.spawnSync('gh', args, { encoding: 'utf8' });
+  const result = cp.spawnSync(GH_BIN, args, { encoding: 'utf8' });
   if (result.error) {
     const err = new Error(`gh binary not found: ${result.error.message}`);
     err.code = 'GH_BIN_MISSING';

package/src/cli/args.js

@@ -108,6 +108,14 @@ function parseCommonArgs(rawArgs, defaults) {
       options.allowProtectedBaseWrite = true;
       continue;
     }
+    if (arg === '--contract' || arg === '--full') {
+      options.contract = true;
+      continue;
+    }
+    if (arg === '--minimal' || arg === '--no-contract') {
+      options.contract = false;
+      continue;
+    }
     if (Object.prototype.hasOwnProperty.call(options, 'waitForMerge') && arg === '--wait-for-merge') {
       options.waitForMerge = true;
       continue;
@@ -177,6 +185,8 @@ function parseSetupArgs(rawArgs, defaults) {
   const setupDefaults = {
     ...defaults,
     parentWorkspaceView: false,
+    speckit: true,
+    speckitForce: false,
   };
   const forwardedArgs = [];
 
@@ -190,6 +200,19 @@ function parseSetupArgs(rawArgs, defaults) {
       setupDefaults.parentWorkspaceView = false;
       continue;
     }
+    if (arg === '--no-speckit' || arg === '--skip-speckit') {
+      setupDefaults.speckit = false;
+      continue;
+    }
+    if (arg === '--speckit') {
+      setupDefaults.speckit = true;
+      continue;
+    }
+    if (arg === '--speckit-force' || arg === '--reinstall-speckit') {
+      setupDefaults.speckit = true;
+      setupDefaults.speckitForce = true;
+      continue;
+    }
     forwardedArgs.push(arg);
   }
 
@@ -1069,6 +1092,10 @@ function parseFinishArgs(rawArgs, defaults = {}) {
     failFast: false,
     commitMessage: '',
     mergeMode: defaults.mergeMode || 'pr',
+    skipPreflight: false,
+    gateReview: defaults.gateReview ?? false,
+    reviewProvider: defaults.reviewProvider || 'codex',
+    allowNoChecks: false,
   };
 
   for (let index = 0; index < rawArgs.length; index += 1) {
@@ -1181,6 +1208,31 @@ function parseFinishArgs(rawArgs, defaults = {}) {
       options.advanceSubmodules = false;
       continue;
     }
+    if (arg === '--skip-preflight') {
+      options.skipPreflight = true;
+      continue;
+    }
+    if (arg === '--gate-review') {
+      options.gateReview = true;
+      continue;
+    }
+    if (arg === '--no-gate-review' || arg === '--skip-review-gate') {
+      options.gateReview = false;
+      continue;
+    }
+    if (arg === '--allow-no-checks') {
+      options.allowNoChecks = true;
+      continue;
+    }
+    if (arg === '--review-provider') {
+      const next = rawArgs[index + 1];
+      if (!next || !['codex', 'claude'].includes(next)) {
+        throw new Error('--review-provider requires a value of codex|claude');
+      }
+      options.reviewProvider = next;
+      index += 1;
+      continue;
+    }
     throw new Error(`Unknown option: ${arg}`);
   }
 
@@ -1194,9 +1246,7 @@ function parseFinishArgs(rawArgs, defaults = {}) {
 module.exports = {
   requireValue,
   normalizeManagedForcePath,
-  collectForceManagedPaths,
   parseCommonArgs,
-  parseRepoTraversalArgs,
   parseSetupArgs,
   parseDoctorArgs,
   parseTargetFlag,