@imdeadpool/guardex 7.0.41 → 7.1.0

package/templates/githooks/pre-commit

@@ -108,6 +108,18 @@ case "$codex_require_agent_branch" in
   *) should_require_codex_agent_branch=1 ;;
 esac
 
+# General lockdown knob (applies to ALL agent sessions, not just Codex).
+# Default OFF: any branch that is not a protected base is an acceptable agent
+# branch, so `vendor/x`, `feat/y`, or any ad-hoc name commits without ceremony.
+# Set GUARDEX_REQUIRE_AGENT_BRANCH=1 (or `git config multiagent.requireAgentBranch
+# true`) to force agent commits back onto the agent/* namespace.
+require_agent_branch_raw="${GUARDEX_REQUIRE_AGENT_BRANCH:-$(git config --get multiagent.requireAgentBranch || true)}"
+require_agent_branch="$(printf '%s' "$require_agent_branch_raw" | tr '[:upper:]' '[:lower:]')"
+should_require_agent_branch=0
+case "$require_agent_branch" in
+  1|true|yes|on) should_require_agent_branch=1 ;;
+esac
+
 is_codex_managed_only_commit_on_protected=0
 if [[ "$is_codex_session" == "1" && "$is_protected_branch" == "1" ]]; then
   deleted_paths="$(git diff --cached --name-only --diff-filter=D)"
@@ -138,8 +150,6 @@ if [[ "$should_require_codex_agent_branch" == "1" && "${GUARDEX_ALLOW_CODEX_ON_N
 GitGuardex requires Codex work to run from an isolated agent/* branch.
 Start the sub-branch/worktree with:
   gx branch start "<task-or-plan>" "<agent-name>"
-Or manually:
-  gx branch start "<task-or-plan>" "<agent-name>"
 Then commit from the created agent/* branch.
 
 Temporary bypass (not recommended):
@@ -147,19 +157,10 @@ Temporary bypass (not recommended):
 MSG
       exit 1
     fi
-
-    cat >&2 <<'MSG'
-[codex-branch-guard] Codex agent commit blocked on non-agent branch.
-Use isolated branch/worktree first:
-  gx branch start "<task-or-plan>" "<agent-name>"
-Then commit from the created agent/* branch.
-
-Temporary bypass (not recommended):
-  GUARDEX_ALLOW_CODEX_ON_NON_AGENT=1 git commit ...
-Disable this rule for a repo (not recommended):
-  git config multiagent.codexRequireAgentBranch false
-MSG
-    exit 1
+    # Non-protected branches (vendor/, feat/, any ad-hoc name) are fine for
+    # Codex too — being OFF a protected base is the only load-bearing rule.
+    # Re-impose the agent/* requirement with GUARDEX_REQUIRE_AGENT_BRANCH=1
+    # (handled by the general lockdown gate below).
   fi
 fi
 
@@ -192,26 +193,49 @@ MSG
   exit 1
 fi
 
-if [[ "$is_agent_session" == "1" && "$branch" != agent/* ]]; then
+if [[ "$is_agent_session" == "1" && "$branch" != agent/* && "$should_require_agent_branch" == "1" ]]; then
   cat >&2 <<'MSG'
-[agent-branch-guard] Agent commits must run on dedicated agent/* branches.
+[agent-branch-guard] Lockdown mode: agent commits must run on dedicated agent/* branches.
+GUARDEX_REQUIRE_AGENT_BRANCH (or multiagent.requireAgentBranch) is enabled.
 Start an agent branch first:
   gx branch start "<task-or-plan>" "<agent-name>"
 Then commit on that branch.
 
-Temporary bypass (not recommended):
-  ALLOW_COMMIT_ON_PROTECTED_BRANCH=1 git commit ...
+Relax (any non-protected branch is normally fine):
+  unset GUARDEX_REQUIRE_AGENT_BRANCH
+  # or: git config multiagent.requireAgentBranch false
 MSG
   exit 1
 fi
 
 if [[ "$branch" == agent/* ]]; then
   if [[ "${GUARDEX_AUTOCLAIM_STAGED_LOCKS:-1}" == "1" ]]; then
+    # Auto-claim non-deletion staged paths. Deletions need an explicit
+    # `--allow-delete` flag below so `locks validate --staged` doesn't
+    # reject the commit on the same trip the user staged the delete.
     while IFS= read -r staged_file; do
       [[ -z "$staged_file" ]] && continue
       [[ "$staged_file" == ".omx/state/agent-file-locks.json" ]] && continue
       run_guardex_cli locks claim --branch "$branch" "$staged_file" >/dev/null 2>&1 || true
-    done < <(git diff --cached --name-only --diff-filter=ACMRDTUXB)
+    done < <(git diff --cached --name-only --diff-filter=ACMRTUXB)
+
+    # Auto-approve deletions for the same branch (gated separately so
+    # operators can disable this single behavior without disabling the
+    # broader auto-claim). Defaults to enabled — matches the auto-claim
+    # default and removes the "first commit fails, then `gx locks
+    # allow-delete`, then commit again" loop.
+    if [[ "${GUARDEX_AUTOCLAIM_STAGED_DELETES:-1}" == "1" ]]; then
+      _staged_deletes=()
+      while IFS= read -r staged_delete; do
+        [[ -z "$staged_delete" ]] && continue
+        [[ "$staged_delete" == ".omx/state/agent-file-locks.json" ]] && continue
+        _staged_deletes+=("$staged_delete")
+      done < <(git diff --cached --name-only --diff-filter=D)
+      if (( ${#_staged_deletes[@]} > 0 )); then
+        run_guardex_cli locks claim --branch "$branch" --allow-delete \
+          "${_staged_deletes[@]}" >/dev/null 2>&1 || true
+      fi
+    fi
   fi
 
   if ! run_guardex_cli locks validate --branch "$branch" --staged; then

package/templates/github/workflows/README.md

@@ -0,0 +1,87 @@
+# `templates/github/workflows/` — budget-friendly CI defaults
+
+Workflow files in this directory are copied into a gitguardex-managed
+project's `.github/workflows/` directory when bootstrapping. They are
+the **default** budget posture for projects that use `gx branch start`
+to drive agent iterations.
+
+Agent flows land a high volume of PRs per month. Without these trims,
+every PR + every post-merge push fans out across CI, CodeQL, Scorecard,
+and Code Review — which dominates the GitHub Actions bill for any
+multi-agent repo. The trims below cut that cost without giving up
+correctness coverage.
+
+## What's trimmed and why
+
+1. **`concurrency: cancel-in-progress: true`** scoped per workflow + ref
+   so rapid pushes to the same agent branch cancel the prior run
+   instead of letting both finish on Actions minutes.
+
+2. **`if: github.event.pull_request.draft == false`** on every job that
+   shouldn't run on a draft PR, paired with
+   `pull_request.types: [..., ready_for_review]` in the trigger list so
+   CI fires the moment the PR is promoted out of draft.
+
+3. **`if: !startsWith(head.ref, 'agent/')`** on the Code Review job
+   (`cr.yml`) — skip AI review on automated agent-lane PRs. AI review
+   on hundreds of agent PRs per month burns both Actions minutes and
+   OpenAI tokens without adding signal; human-authored PRs (any non-
+   `agent/*` head branch) still get reviewed.
+
+4. **No `push: main` trigger** in `ci.yml` — branch protection on
+   `main` forces all changes through a PR, so PR-time CI is sufficient
+   and post-merge CI on `main` was pure duplication. Use
+   `workflow_dispatch` for ad-hoc full runs.
+
+5. **`paths-ignore`** for docs / openspec / template-only changes — skip
+   CI on changes that don't affect runtime behavior.
+
+## Customizing
+
+- Replace `placeholder` steps in `ci.yml` with your build/test/lint
+  commands.
+- Keep the `concurrency:`, `if:`, and `paths-ignore:` patterns. They
+  are the load-bearing part of the budget posture; removing them undoes
+  the win.
+
+## When to skip the draft-skip pattern
+
+If your CI is fast (≤ 2 min) and you want continuous validation as
+agents iterate, drop the `if: pull_request.draft == false` job guard.
+The concurrency cancel alone still prevents minute pile-up.
+
+## When to re-enable AI code review on agent PRs
+
+If your team relies on AI review as a true gating signal (not just
+advisory), remove the `!startsWith(head.ref, 'agent/')` guard in
+`cr.yml`. Expect the OpenAI bill to scale linearly with merge volume.
+
+## Per-PR label opt-in
+
+Both `cr.yml` and `ci-full.yml` honor PR labels so the occasional
+agent PR that actually needs the heavier check can opt in without
+flipping a global toggle:
+
+| Label | Effect |
+| --- | --- |
+| `needs-review` | Run AI code review on this PR even though it's `agent/*`. Useful for security-sensitive changes or public-API redesigns. |
+| `needs-ci-full` | Run the full cross-runtime matrix from `ci-full.yml` on this PR instead of waiting for the weekly schedule. Useful before a release branch lands. |
+
+To enable: open the PR, then `gh pr edit <num> --add-label needs-review`
+(or click the labels picker in the GitHub UI). The label-trigger fires
+the workflow immediately; you don't need to re-push.
+
+Add label definitions to your repo with `gh label create needs-review
+--description "Run AI code review on this PR"` and similar for
+`needs-ci-full`, or define them in `.github/labels.yml` if you use a
+label-sync workflow.
+
+## What about CodeQL / Scorecard?
+
+The gitguardex repo itself runs CodeQL and Scorecard on the **weekly
+schedule + `workflow_dispatch`** only — not on per-PR / per-push
+triggers. Those workflows are long-running (5–10 min for CodeQL) and
+were the largest single line item on the monthly Actions bill before
+this change. If your project needs per-PR CodeQL gating for compliance
+reasons, re-add the `pull_request` trigger and accept the cost; for
+most repos, weekly + on-demand is the right default.

package/templates/github/workflows/ci-full.yml

@@ -0,0 +1,55 @@
+# Optional companion to `ci.yml`. Drop in alongside it when your
+# project supports multiple runtimes / OS combinations and you want
+# coverage across all of them without paying per-PR.
+#
+# Strategy: PR-time `ci.yml` runs the primary runtime only (cheap).
+# This workflow runs the full matrix on the weekly schedule, and
+# on-demand via `workflow_dispatch` before a release. Per-PR opt-in
+# is available by applying the `needs-ci-full` label to a PR.
+#
+# Customize the matrix rows below to match your supported runtimes.
+
+name: CI (full matrix)
+
+on:
+  schedule:
+    - cron: '15 4 * * 1'
+  workflow_dispatch:
+  pull_request:
+    types: [labeled, synchronize]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-full-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (node ${{ matrix.node }})
+    # PR runs only fire when the `needs-ci-full` label is present.
+    # Schedule and workflow_dispatch always run.
+    if: >-
+      github.event_name != 'pull_request' ||
+      contains(github.event.pull_request.labels.*.name, 'needs-ci-full') ||
+      (github.event.action == 'labeled' && github.event.label.name == 'needs-ci-full')
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [18, 22]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: ${{ matrix.node }}
+
+      # Replace below with your build/test/lint steps. Keep them parallel
+      # to `ci.yml` so the weekly matrix matches what runs per-PR.
+      - name: Project verification placeholder
+        run: echo "Replace this step with your build/test/lint commands."

package/templates/github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# Budget-friendly CI default for gitguardex-managed projects.
+#
+# Four trims keep Actions minutes low while agent branches iterate:
+#   1. `concurrency: cancel-in-progress` — rapid pushes to the same ref
+#      kill the prior run instead of letting both finish.
+#   2. Job-level `if: pull_request.draft == false` plus the
+#      `ready_for_review` PR trigger — draft PRs skip CI, and CI fires
+#      automatically the moment the PR is promoted out of draft.
+#   3. `paths-ignore` for docs / openspec / template-only changes —
+#      skip CI on changes that don't affect runtime behavior.
+#   4. No `push: main` trigger — branch-protection-required PR runs
+#      already cover correctness, and post-merge CI on main is pure
+#      duplication. Use `workflow_dispatch` for ad-hoc full runs.
+#
+# Copy this file to `.github/workflows/ci.yml` in your project and
+# replace the placeholder `steps:` block with your build/test/lint
+# commands.
+
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, reopened, synchronize, ready_for_review]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'openspec/**'
+      - '.github/ISSUE_TEMPLATE/**'
+      - '.github/PULL_REQUEST_TEMPLATE.md'
+      - '.changeset/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Replace below with your build/test/lint steps. Examples:
+      # - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      #   with: { node-version: '20' }
+      # - run: npm ci
+      # - run: npm test
+      - name: Project verification placeholder
+        run: echo "Replace this step with your build/test/lint commands."

package/templates/github/workflows/cr.yml

@@ -2,14 +2,33 @@ name: Code Review
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize]
+    types: [opened, reopened, synchronize, ready_for_review, labeled]
 
 permissions:
   contents: read
   pull-requests: write
 
+# Budget-friendly default for gitguardex-managed projects: cancel
+# superseded runs on the same PR so rapid agent pushes don't fan-out
+# the OpenAI bill.
+concurrency:
+  group: cr-${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
 jobs:
   review:
+    # Skip on draft PRs and on `agent/*` head branches by default.
+    # Agent PRs can opt-in by applying the `needs-review` label —
+    # useful for the occasional agent PR that genuinely needs AI
+    # eyes (security-sensitive change, public-API redesign, etc.).
+    # Human-authored PRs (any non-`agent/*` head branch) always run.
+    if: >-
+      github.event.pull_request.draft == false &&
+      (
+        !startsWith(github.event.pull_request.head.ref, 'agent/') ||
+        contains(github.event.pull_request.labels.*.name, 'needs-review') ||
+        (github.event.action == 'labeled' && github.event.label.name == 'needs-review')
+      )
     runs-on: ubuntu-latest
     env:
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}