@imdeadpool/guardex 7.0.39 → 7.0.43

package/templates/AGENTS.multiagent-safety.md

@@ -1,63 +1,447 @@
 <!-- multiagent-safety:START -->
-## Multi-Agent Execution Contract (GX)
+## Multi-Agent Execution Contract: Guardex + Colony
 
-**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.
+### Repo toggle
 
-**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.
+Guardex is enabled by default.
 
-**Task-size routing.** Small tasks stay in direct caveman-only mode. For typos, single-file tweaks, one-liners, version bumps, or similarly bounded asks, solve directly and do not escalate into heavy OMX orchestration just because a keyword appears. Treat `quick:`, `simple:`, `tiny:`, `minor:`, `small:`, `just:`, and `only:` as explicit lightweight escape hatches.
-Promote to OMX orchestration only when the task is medium/large: multi-file behavior changes, API/schema work, refactors, migrations, architecture, cross-cutting scope, or long prompts. Heavy OMX modes (`ralph`, `autopilot`, `team`, `ultrawork`, `swarm`, `ralplan`) are for that larger scope. If the task grows while working, upgrade then.
+If the repo-root `.env` sets any of these values, treat this entire Guardex contract as disabled for the repo:
 
-## Token / Context Budget
+```text
+GUARDEX_ON=0
+GUARDEX_ON=false
+GUARDEX_ON=no
+GUARDEX_ON=off
+```
+
+When disabled, do not require Guardex worktrees, lock claims, completion flow, or OpenSpec workflow until `GUARDEX_ON` is re-enabled.
+
+To explicitly enable:
+
+```text
+GUARDEX_ON=1
+```
+
+### Core rules
+
+- Work from an `agent/*` branch and worktree, never directly on the protected base branch.
+- Claim files before edits.
+- Use Colony for coordination before falling back to OMX state/notepad.
+- Prefer fff MCP tools for file search whenever available; do not route file search through RTK when fff can answer it.
+- Use OpenSpec for durable behavior contracts and change-driven work.
+- Keep outputs compact: less word, same proof.
+- Commit, push, and open/update a PR for completed work unless the user explicitly says to keep it local.
+- Do not embed stale memory dumps, generated status snapshots, PR transcripts, session history, or long logs in this file.
+
+### Task-size routing
+
+Small tasks stay direct and caveman-only.
+
+For typos, single-file tweaks, one-liners, version bumps, comment-only changes, or similarly bounded asks, solve directly and do not escalate into heavy orchestration just because a keyword appears.
+
+Treat these prefixes as explicit lightweight escape hatches:
+
+- `quick:`
+- `simple:`
+- `tiny:`
+- `minor:`
+- `small:`
+- `just:`
+- `only:`
+
+Promote to full Guardex / OMX orchestration only when scope grows into:
+
+- multi-file behavior change
+- API/schema work
+- refactor
+- migration
+- architecture
+- cross-cutting scope
+- long prompt
+- multi-agent execution
+
+### Colony coordination loop
+
+Use Colony as the primary coordination surface.
+
+On every startup, resume, follow-up, or "continue" request, run this order:
+
+1. `mcp__colony__hivemind_context`
+2. `mcp__colony__attention_inbox`
+3. `mcp__colony__task_ready_for_agent`
+4. `mcp__colony__search` only when prior decisions, earlier lanes, file history, or error context matter.
+
+Rules:
+
+- Use `task_ready_for_agent` to choose work.
+- Use `task_list` only for browsing/debugging. Do not use `task_list` as the normal work picker.
+- If an agent reaches for `task_list` repeatedly while choosing work, stop and call `task_ready_for_agent` instead. `task_list` is an inventory tool, not a scheduler.
+- Before editing files on an active task, call `task_claim_file` for each touched file.
+- Use `task_post` for task-thread notes, decisions, blockers, and working-state updates.
+- Use `task_message` / `task_messages` for directed agent-to-agent communication.
+- Use `get_observations` only after compact Colony tools return IDs worth hydrating.
+
+Fallback:
+
+- Colony is considered unavailable only when the MCP namespace is missing, the tool call fails, or the installed Colony server does not expose the required tool.
+- If `attention_inbox` or `task_ready_for_agent` is missing, fall back to `hivemind_context`, then `task_list`, then hydrate only the relevant task IDs.
+- Do not skip Colony just because OMX state exists. OMX is fallback, not the first coordination source.
+- Read `.omx/state` and `.omx/notepad.md` only when Colony is unavailable, missing the needed state, or the task explicitly depends on legacy OMX state.
+- Keep `.omx/notepad.md` lean: live handoffs only.
+
+### Working-state notes
+
+Colony is preferred over generic notepad state.
+
+A working-state note should be task-scoped, searchable, and useful to another agent resuming the lane.
+
+When saving progress, use a task-scoped Colony note when possible:
+
+```text
+task_post kind=note
+content="branch=<branch>; task=<task>; blocker=<blocker>; next=<next>; evidence=<path|command|PR|spec>"
+```
+
+Use exactly these fields for handoff-style notes:
+
+- `branch`
+- `task`
+- `blocker`
+- `next`
+- `evidence`
+
+Do not store long proof dumps, stale narrative, or full logs in notepads. Put bulky proof in OpenSpec artifacts, PRs, or command output.
+
+### Token / context budget
 
 Default: less word, same proof.
 
-- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode: plan in at most 4 bullets, execute by phase, batch related reads/commands, avoid duplicate reads and interactive loops, keep outputs compact, and verify once per phase.
-- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine; low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
-- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next step`, and `evidence`.
-- Memory-driven starts stay ordered: read active `.omx/state` first, then one live `.omx/notepad.md` handoff, then external memory only when the task depends on prior repo decisions, a previous lane, or ambiguous continuity. Stop after the first 1-2 relevant hits.
-- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that only rediscover the same path state.
-- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals. If they appear alongside climbing input cost, stop the probe loop and batch the next phase.
+- For prompts about `token inefficiency`, `reviewer mode`, `minimal token overhead`, or session waste patterns, switch into low-overhead mode.
+- Plan in at most 4 bullets.
+- Execute by phase.
+- Batch related reads and commands.
+- Avoid duplicate reads and interactive loops.
+- Keep outputs compact.
+- Verify once per phase.
+- Low output alone is not a defect. A bounded run that finishes in roughly <=10 steps is usually fine.
+- Low output spread across 20+ steps with rising per-turn input is fragmentation and should be treated as context growth first.
+- Startup / resume summaries stay tiny: `branch`, `task`, `blocker`, `next`, and `evidence`.
+- Front-load scaffold/path discovery into one grouped inspection pass. Avoid serial `ls` / `find` / `rg` / `cat` retries that rediscover the same path state.
+- Treat repeated `write_stdin`, repeated `sed` / `cat` peeks, and tiny diagnostic follow-up checks as strong negative signals.
+- If a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
 - Tool / hook summaries stay tiny: command, status, last meaningful lines only. Drop routine hook boilerplate.
 - Keep raw terminal interaction out of long-lived context. For `write_stdin` or interactive babysitting, retain only process, action sent, current result, and next action.
 - Keep execution log separate from reasoning context: full commands/stdout belong in logs, while prompt context keeps only the latest 1-2 checkpoints plus the newest tool-result summary.
-- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases. Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
-- When a session turns fragmented, collapse back to inspect once, patch once, verify once, and summarize once.
-- Use a fixed checkpoint shape when compacting: `Task`, `Done`, `Current status`, and `Next`.
-- Keep `.omx/notepad.md` lean: live handoffs only. Use exactly `branch`, `task`, `blocker`, `next step`, and `evidence`; move narrative proof into OpenSpec artifacts, PRs, or command output.
+- Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases.
+- Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
+
+### RTK command compression
 
-## OMX Caveman Style
+When `rtk` is available, prefer it for noisy shell discovery and verification. For file search, fff MCP takes precedence whenever available.
 
-- Commentary and progress updates use smart-caveman `ultra` by default: drop articles, filler, pleasantries, and hedging. Fragments are fine when they stay clear.
-- Answer order stays fixed: answer first, cause next, fix or next step last. If yes/no fits, say yes/no first.
-- Keep literals exact: code, commands, file paths, flags, env vars, URLs, numbers, timestamps, and error text are never caveman-compressed.
-- Auto-clarity wins: switch back to `lite` or normal wording for security warnings, irreversible actions, privacy/compliance notes, ordered instructions where fragments may confuse, or when the user is confused and needs more detail.
-- Boundaries stay normal/exact for code, commits, PR text, specs, logs, and blocker evidence.
+- Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.
+- Git and GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.
+- Tests and builds: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.
+- Runtime and data probes: `rtk docker ps`, `rtk docker logs <container>`, `rtk kubectl pods`, `rtk json <file>`, `rtk log <file>`, `rtk curl <url>`.
+- Savings checks: `rtk gain`, `rtk discover`, and `rtk session`.
+- Use `rtk proxy <command>` only when raw passthrough is required.
+- Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).
+- If `rtk` is missing, use raw commands and summarize only meaningful lines.
+
+### FFF file search
+
+Use the fff MCP tools for all file search operations instead of default tools, including RTK shell wrappers.
+
+If fff MCP tools are unavailable in the current client, fall back to `rtk grep`, `rtk find`, `rtk ls`, or `rg` and keep output compact.
+
+### Caveman style
+
+Commentary and progress updates use smart-caveman `ultra` by default:
+
+- Answer order stays fixed: answer first, cause next, fix or next step last.
+- drop filler
+- use fragments when clear
+- answer first
+- cause next
+- fix or next step last
+
+Keep exact literals unchanged:
+
+- code
+- commands
+- file paths
+- flags
+- env vars
+- URLs
+- numbers
+- timestamps
+- error text
+
+Switch back to `lite` or normal wording for:
+
+- security warnings
+- irreversible actions
+- privacy/compliance notes
+- ordered instructions where fragments may confuse
+- confused users
+- commits
+- PR text
+- specs
+- logs
+- blocker evidence
+
+Never caveman-compress commands, file paths, specs, logs, or blocker evidence.
+
+### Isolation
+
+Every task runs on a dedicated `agent/*` branch and worktree.
+
+Start with:
+
+```bash
+gx branch start "<task>" "<agent-name>"
+```
+
+Treat the base branch (`main` / `dev`) as read-only while an agent branch is active.
 
-**Isolation.** Every task runs on a dedicated `agent/*` branch + worktree. Start with `gx branch start "<task>" "<agent-name>"`. Treat the base branch (`main`/`dev`) as read-only while an agent branch is active. The `.githooks/post-checkout` hook auto-reverts primary-branch switches during agent sessions and auto-stashes a dirty tree before reverting - 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.
 
-**Primary-tree lock (blocking).** On the primary checkout, do NOT run any of: `git checkout <ref>`, `git switch <ref>`, `git switch -c ...`, `git checkout -b ...`, or `git worktree add <path> <existing-agent-branch>`. The only branch-changing commands allowed on primary are `git fetch` and `git pull --ff-only` against the protected branch itself. To work on any `agent/*` branch, run `gx branch start ...` first, then `cd` into the printed `.omc/agent-worktrees/...` path and run every subsequent git command from inside that worktree. If you find yourself typing `git checkout agent/...` or `git switch agent/...` from the primary cwd, stop - that is the mistake that flips primary onto an agent branch.
+Never implement directly on the local/base branch checkout. Keep it unchanged and perform all edits in the agent sub-branch/worktree.
+
+### Primary-tree lock
+
+On the primary checkout, do not run:
+
+```bash
+git checkout <ref>
+git switch <ref>
+git switch -c ...
+git checkout -b ...
+git worktree add <path> <existing-agent-branch>
+```
+
+Allowed on primary:
+
+```bash
+git fetch
+git pull --ff-only
+```
+
+To work on any `agent/*` branch, run `gx branch start ...` first, then `cd` into the printed worktree path and run every subsequent git command from inside that worktree.
+
+If you are about to type `git checkout agent/...` or `git switch agent/...` from the primary checkout, stop. That is the mistake that flips primary onto an agent branch.
+
+### Dirty-tree rule
+
+Finish or stash edits inside the worktree they belong to before any branch switch on primary.
+
+The post-checkout guard may auto-stash a dirty primary tree as:
+
+```text
+guardex-auto-revert <ts> <prev>-><new>
+```
+
+That is a safety net, not a workflow. Do not rely on it routinely.
+
+Recover stashed changes with:
+
+```bash
+git stash list | grep 'guardex-auto-revert'
+```
+
+### Ownership
+
+Before editing, claim files.
+
+Preferred Colony path when on an active task:
+
+```text
+mcp__colony__task_claim_file
+```
+
+Guardex lock path:
+
+```bash
+gx locks claim --branch "<agent-branch>" <file...>
+```
+
+Before deleting, confirm the path is in your claim.
+
+Do not edit outside your scope unless reassigned.
+
+If another agent owns or recently touched nearby code:
+
+1. read latest Colony context
+2. post a handoff or question
+3. avoid reverting unrelated changes
+4. report conflicts instead of overwriting
+
+### Handoff gate
+
+Before editing, post a one-line handoff note through Colony `task_post` when a task is active.
+
+Use `.omx/notepad.md` only when Colony is unavailable or the lane explicitly depends on legacy OMX state.
+
+Handoff shape:
+
+```text
+branch=<branch>; task=<task>; blocker=<blocker>; next=<next>; evidence=<path|command|PR|spec>
+```
+
+Re-read latest Colony context before replacing another agent's code.
+
+### Completion
+
+Finish with:
+
+```bash
+gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup
+```
+
+or:
+
+```bash
+gx finish --all
+```
+
+Task is complete only when:
+
+1. changes are committed
+2. branch is pushed
+3. PR URL is recorded
+4. PR state is `MERGED`
+5. sandbox worktree is pruned
+6. final handoff records proof
+
+If anything blocks, append a `BLOCKED:` note and stop. Do not half-finish.
+
+OMX completion policy: when a task is done, the agent must run `gx branch finish --branch "<agent-branch>" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`) instead of standalone `git push` / `gh pr` commands. The finish flow owns commit, push, PR creation/update, merge wait, and sandbox cleanup.
+
+External approval boundary:
+
+- Guardex cannot bypass Codex host approval prompts or external-remote policy decisions.
+- When the host blocks a publish or finish command, request approval for the narrow `gx branch finish ...` command, or for the exact session wrapper that invokes it, and continue after approval.
+- Do not replace the finish flow with repeated standalone `git push` / `gh pr` attempts. That increases approval churn and can strand PR, merge, or cleanup state.
+
+### Parallel safety
+
+Assume other agents edit nearby.
+
+- Never revert unrelated changes.
+- Never simplify or delete critical shared paths without explicit request and regression coverage.
+- Report conflicts in the handoff.
+- Prefer compatibility-preserving changes over endpoint-specific rewrites when other agents may be changing adjacent systems.
+
+### Reporting
+
+Every completion handoff includes:
+
+```text
+branch
+task
+files changed
+behavior touched
+verification commands/results
+PR URL
+merge state
+sandbox cleanup state
+risks/follow-ups
+```
+
+If blocked, use:
+
+```text
+BLOCKED:
+branch=<branch>
+task=<task>
+blocker=<blocker>
+next=<next>
+evidence=<path|command|PR|spec>
+```
+
+### Open questions
+
+If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in:
+
+```text
+openspec/plan/<plan-slug>/open-questions.md
+```
+
+as an unchecked item:
+
+```md
+- [ ] Question or blocker...
+```
+
+Resolve it in-place when answered instead of burying it in chat-only notes.
+
+### OpenSpec
+
+OpenSpec is the source of truth for change-driven repo work.
+
+For change-driven tasks, keep:
+
+```text
+openspec/changes/<slug>/tasks.md
+```
+
+current during work, not batched at the end.
+
+Task scaffolds and manual task edits must include a final completion/cleanup section that ends with PR merge + sandbox cleanup and records PR URL + final `MERGED` evidence.
+
+Validate specs before archive:
+
+```bash
+openspec validate --specs
+```
+
+Never archive unverified work.
+
+For `T0` / small `T1` lanes, use the compact Colony spec path when available. One Colony handoff plus `colony-spec.md` is enough. Do not create proposal/spec/tasks unless the task grows.
+
+For `T2` / `T3` lanes, keep proposal, spec, design, and tasks live while implementing.
+
+### Version bumps
+
+If a change bumps a published version, the same PR records release notes in the appropriate OpenSpec artifact or release-note mechanism for the repo.
+
+Do not edit `CHANGELOG.md` directly unless the repo explicitly requires manual changelog edits.
+
+### Verification gates
+
+Before claiming completion, run the narrowest meaningful verification for the touched area.
+
+Examples:
 
-**Dirty-tree rule.** Finish or stash edits inside the worktree they belong to before any branch switch on primary. The post-checkout guard auto-stashes a dirty primary tree as `guardex-auto-revert <ts> <prev>-><new>` before reverting, but that is a safety net, not a workflow; do not rely on it routinely. Recover stashed changes with `git stash list | grep 'guardex-auto-revert'`.
+```bash
+pnpm test
+pnpm typecheck
+pnpm lint
+```
 
-**Ownership.** Before editing, claim files: `gx locks claim --branch "<agent-branch>" <file...>`. Before deleting, confirm the path is in your claim. Don't edit outside your scope unless reassigned.
+If a command cannot run, record:
 
-**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.
+```text
+command
+reason it could not run
+risk
+next
+```
 
-**Completion.** Finish with `gx branch finish --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.
+Do not claim green verification without command output evidence.
 
-**Parallel safety.** Assume other agents edit nearby. Never revert unrelated changes. Report conflicts in the handoff.
+### What not to put in this file
 
-**Reporting.** Every completion handoff includes: files changed, behavior touched, verification commands + results, risks/follow-ups.
+Do not embed:
 
-**Open questions.** If Codex/Claude hits an unresolved question, branching decision, or blocker that should survive chat, record it in `openspec/plan/<plan-slug>/open-questions.md` as an unchecked `- [ ]` item. Resolve it in-place when answered instead of burying it in chat-only notes.
+- stale memory dumps
+- PR transcripts
+- long logs
+- generated status snapshots
+- session history
+- full OpenSpec examples
+- repeated copies of long workflow docs
 
-**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 `gx branch finish ... --cleanup`) and records PR URL + final `MERGED` evidence. Verify specs with `openspec validate --specs` before archive. Don't archive unverified.
+Keep this section as the hard multi-agent contract. Put long examples and recovery docs in repo-specific workflow docs.
 
-**Version bumps.** If a change bumps a published version, the same PR updates release notes/changelog.
 <!-- multiagent-safety:END -->

package/templates/codex/skills/gitguardex/SKILL.md

@@ -9,3 +9,5 @@ Use when repo safety may be broken.
 
 Bootstrap: `gx setup`
 Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`
+
+When inspecting or verifying, prefer `rtk` compact wrappers if available (`rtk git status`, `rtk grep`, `rtk test <cmd>`). Do not wrap commands whose stdout is parsed by scripts.

package/templates/githooks/pre-commit

@@ -207,11 +207,32 @@ 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."