Practical Guardrails for Coding Agents

AI coding agents ship code fast and cut every corner doing it: skipped tests, ignored lint failures, --no-verify to bypass hooks, amended history to hide the mess.

WORKSPACE-CI generates native git hooks from a single config file and hard-enforces lint, tests, secrets, and coverage at commit and push time. With WORKSPACE-GUARD, it blocks every escape hatch (--no-verify, --force, --amend, git reset) at the syscall boundary. The agent cannot cheat.

Ask an agent why it skipped the tests and you'll get a confident hallucination about its own limitations instead of a fix:

How it works

workspace-ci reads your .pre-commit-config.yaml and generates native .git/hooks/* bash scripts. No framework runtime, no pip install on the developer machine beyond the initial workspace bootstrap, no remote hook repos to clone.

The execution model is three stages with non-redundant responsibility:

A separate capability-based binary (WORKSPACE-GUARD) wraps git via dpkg-divert and enforces guardrails at the syscall boundary: blocks --no-verify, --force pushes, git reset, git checkout --hard, git commit --amend, standalone git rebase, git stash drop, dangerous config keys (core.hookspath, core.sshcommand, alias.*, etc.), and sanitizes the child environment to an allow-list. Identity and editor config keys are sudo-gated. This ensures hooks actually run and history cannot be rewritten.

Shell handles everything that doesn't need a full programming language: file listing, pattern matching, conditional logic, formatter auto-stage, dead-code analysis via the dangle binary (cargo install dangle). Python handles what shell can't: multi-file regex at scale and network requests (dependency freshness, markdown link probing).

---

Quick Start

# 1. Clone or copy workspace-ci into your monorepo (e.g. projects/CI/)
cd projects/CI

# 2. Bootstrap system deps (macOS Homebrew + apt on Linux) and toolchain
make init          # once per machine: Homebrew/apt, Rust if missing
make install       # bootstrap uv, gitleaks, cloc, moon, ansible, node;
                   # uv sync (.venv), npm install (web/), generate hooks

# 3. Regenerate hooks after config changes
make install-hooks

# 4. Run the full pre-push gate locally before pushing
make check-push

For monorepo setups with shared config, see docs/runbooks/RUNBOOK-HOOKS.md and docs/requirements/REQ-BOOT-LAYOUT.md: covers the Makefile contract, platform-aware $(BOOT_NAME) boot directories, ci_resolve_boot_path walk-up, moon.yml::project.inherited_boot_dirs, and tier configuration.

Consumer projects that only need hooks (no full CI install):

bash projects/CI/scripts/generate-hooks

---

What Gets Checked

Every hook's stage is configured in .pre-commit-config.yaml and can be moved freely. The table below shows the default wiring for the workspace root config. Scope describes which files the check scans when triggered. Checks marked advisory print warnings but do not block the commit or push.

Every check has configurable always_run / files: / stages: / types_or: gates in .pre-commit-config.yaml and an enforcement tier (strict / poc / vendored) resolved via project_enforcement.yaml. POC tier runs only secrets, sensitive files, banned words, and commit hygiene; vendored tier installs no hooks.

All rules are config-driven. Patterns live in config/banned_words.yaml (with per-project overrides in banned_words_exceptions.yaml), file rules in config/sensitive_files.yaml, coverage gates in config/coverage_thresholds.yaml, hook registry in config/required_hooks.yaml, boot layout in moon.yml (project.inherited_boot_dirs), file length limits in config/file_length_limits.yaml, dead code rules in config/dead_code.yaml, markdown doc targets in config/markdown_docs.yaml, blocked commit patterns in config/blocked_commit_patterns.yaml, and dependency excludes in config/dependency_excludes.yaml. Add a pattern, tune a threshold, exclude a path: no code changes needed.

Runtime config overrides

Any config/<stem>.yaml file can be redirected at runtime without copying the whole config/ tree. Resolution is unified across bash hooks, Python checkers, and the wiki (ci/paths.py, ci_config_path in lib/ci_config_paths.sh, web/src/lib/config-paths.ts).

Example manifest (CI_CONFIG_OVERRIDES=/path/to/overrides.yaml):

banned_words: /custom/banned_words.yaml
required_hooks: ./my-required_hooks.yaml

---

Tiers

enforcement_mode: warn during rollout: see violations without breaking flow. Flip to enforce when gates are clean.

---

What workspace-ci adds beyond the tools it wraps

workspace-ci calls ruff, gitleaks, and mypy as subprocesses. It is not a replacement for them. The real question is what you get beyond wiring those same tools into pre-commit yourself.

The floor: DIY pre-commit + ruff + gitleaks + mypy

You get format, lint, type-check, and secret scanning. You also get a Python runtime dependency for every hook run, working-tree stashing on each commit, and remote repo cloning on first run. That is the cost of admission for pre-commit's hook scheduling.

The ceiling: what workspace-ci adds on top of those same tools

The tools workspace-ci wraps are the floor, not the ceiling. The value is the enforcement layer above them.

---

Wiki

The interactive documentation wiki lives in web/ (Next.js).

Production deploy (boot-persistent): copy .env.example to .env (gitignored), then in order:

1. make -C ../WORKSPACE-GATEWAY gateway-deploy: gateway + Grafana on boot
2. make wiki-prod-build && make wiki-prod-deploy: wiki prod on boot (TLS + renewal timer)
3. make wiki-tunnel-deploy: syncs Cloudflare ingress to WIKI_TUNNEL_ORIGIN and starts tunnel

Grafana lives in WORKSPACE-GATEWAY (gw-grafana, loopback :3030, GRAFANA_ROOT_URL for prod). Dev wiki proxies /grafana/ to :3030 with auth headers (same pattern as prod nginx); leave GRAFANA_BASE_URL unset in ~/.config/wiki-ci-dev.env so iframe URLs stay same-origin on :4000. Direct :3030/d/... embeds redirect to workspaceguardrails.com when the gateway is configured for production. Prod wiki proxies /grafana/ through nginx to gw-grafana. If Grafana is down, /llm-gateway shows a styled Service Unavailable panel instead of a blank iframe.

Token-mode tunnels read ingress from Cloudflare remotely; wiki-tunnel-deploy pushes https://127.0.0.1:<WIKI_HTTPS_PORT> via the Cloudflare API when WIKI_TUNNEL_ID and API credentials are set. See res/ansible/tunnel.yml. cloudflared is resolved via scripts/resolve-cloudflared.sh (boot-dir walk-up or PATH) when CLOUDFLARED_BIN is unset.

---

WORKSPACE-GUARD install

WORKSPACE-GUARD is a separate repo; CI provides build and install targets that wrap it via lib/guard-build.sh and lib/guard-install.sh:

# Operator (requires sudo; preserve SSH agent for git clone if needed):
sudo --preserve-env=HOME,SSH_AUTH_SOCK make build-guard
sudo --preserve-env=HOME,SSH_AUTH_SOCK make install-guard

# Read-only status check (no sudo):
make check-guard

make rewrite-history strips blocked patterns from git history and requires WORKSPACE_GUARD_ADMIN=1 when guard is installed.

---

Documentation

---

FAQ

Why not just use pre-commit?

workspace-ci uses the same .pre-commit-config.yaml format, but generates native .git/hooks/* bash scripts instead of running a Python framework. Result: no stashing, no Python runtime dependency for hooks, and no remote git ref pulls.

Does it work for non-Python projects?

Yes. The shell layer: secrets, banned patterns, file length, error-swallow patterns, commit hygiene, coverage gates: treats every language the same. The error-swallow detector spans Python (except: pass), JavaScript/TypeScript (catch {}), Shell (|| true), Ansible ignore_errors, and more via regex. Dead-code analysis via dangle covers 13 languages when installed (cargo install dangle); skips with a warning if absent. The Python layer (dependency version checks, markdown refs, boot layout audit) is Python-only.

Can agents bypass it?

Pre-commit hooks fail closed. Pre-push scans the push range for co-authored and agent-attribution patterns: anything snuck in via rebase or amend gets blocked. WORKSPACE-GUARD wraps the git binary itself and refuses --no-verify, force-push to main, and other escape hatches.

---

License: MIT