BizGuard: a business safety gate for AI coding assistants

BizGuard is an open-source validation project: it checks whether a change would break the business rules that are easy to overlook in the system, before an AI coding assistant modifies the code.

It can work with coding assistants like Claude Code and Codex: the assistant is responsible for writing code, and BizGuard provides a traceable blocking verdict when a critical rule is broken. It is not a production grade security product, nor a replacement for human judgment.

What problem does it solve?

AI is very good at changing code according to the requirements, but it may not know the rules of the system that you are not allowed to touch. What makes it worse is that these rules are often not written in comments: for example, a coupon can only be redeemed once, ledger state must always be consistent, and externally returned data fields cannot be removed at will.

Take an example: when AI modifies the coupon redemption logic, the idempotency key check is removed to save code. The idempotency key can be understood as the unique identifier of this request; with it, repeated clicks or network retries would not redeem the same coupon twice. The code may still compile and ordinary tests may still pass, but duplicate redemptions could happen when a user submits repeatedly.

Traditional LLM code review is more like a second AI making a probabilistic guess about "is there a risk here?" afterwards. It helps, but the result is probabilistic. BizGuard, in contrast, treats explicit business rules as executable policies before the change moves to the next step. It uses syntax-tree inspection (AST, the program structure rather than plain text) and fixed rules to produce deterministic conclusions: the same input can be replayed offline, and the conclusion will not rely on the model's momentary judgment.

Related MCP server: Architect-to-Product (A2P)

Why build this project?

Complex business systems hide many business invariants, which are constraints that must remain valid no matter how the code changes. For example:

• Idempotency: duplicate requests must not deduct, redeem, or deliver twice;

• Ledger consistency: transaction status and ledger records must not contradict each other;

• DTO compatibility: DTO is a data structure passed between services, and externally visible fields must not quietly break callers.

Such knowledge is often scattered across incident reports, interface contracts, team documents, and multiple services. Existing products like CodeRabbit mostly rely on post-hoc LLM review; they are good at surfacing clues but cannot guarantee that all hidden invariants are always recognized.

BizGuard's approach is to turn important invariants into clear and executable policies, then support the decision with AST validation, impact analysis, and an evidence chain. It follows three bottom-line principles:

• Deterministic: the conclusion can be replayed offline;

• Evidence chain: each BLOCK conclusion can be traced back to the rule, the change, and the evidence;

• Unknown is not treated as safe: even if the information is incomplete, return CHECK_INCOMPLETE or REQUIRE_APPROVAL instead of arbitrarily saying ALLOW.

Technical architecture

The project is built incrementally from P0 to P5; here "P" is a phase number, not a manual walkthrough.

flowchart LR
    P0[P0：3 个 Java 脱敏 fixture 仓库\n语义 catalog] --> P1[P1：领域契约\n黄金基准]
    P1 --> P2[P2：知识 Hub\n混合检索]
    P2 --> P3[P3：跨服务影响图谱\n8 类节点 · 真 BFS]
    P3 --> P4[P4：Context Compiler\n8 个 MCP Tool]
    P4 --> P5[P5：四态决策 · 审批 · CI\n5 组消融]
    P5 --> D[带证据的安全结论]

• P0: provide three desensitized Java fixture repositories coupon-core, coupon-contract, and merchant-service, plus a semantic catalog describing business capabilities, rules, and owners.

• P1: pin the domain contracts to a verifiable golden baseline so the rules do not drift away from implementation.

• P2: a knowledge Hub gathers the governed team knowledge, and hybrid search combines semantic vectors with keyword-based results. A frozen Recall@5=1.0 on the eval set only means that the top-5 results in this small, fixed set contain the target; it does not represent a general recall rate in production.

• P3: build a cross-service impact graph covering organization, deployment, code, interface, data, message, runtime, and business as 8 node types, use real BFS (breadth-first search) to find the shortest impact path, and return evidence along the path. When dynamic boundaries cannot be confirmed, they are explicitly marked as unknown.

• P4: Code Context Compiler compiles the task, repository, baseline version, rules, impact and required tests into a read-only context pack, exposed to the Agent through 8 MCP Tools.

• P5: aggregate into a decision of four states, connect with the troubleshooting approval workflow and the CI re-check, and provide 5 sets of offline comparable ablation groups: Naive Baseline, Rules Only, RAG Only, Context, Full.

The four states are straightforward: ALLOW, which means it can proceed; ALLOW_WITH_TESTS, which means it can continue after the specified tests are added; REQUIRE_APPROVAL, which means manual approval; and BLOCK, which means interruption due to critical violations. When existing inspection pipelines cannot find a way to inspect, they would explicitly provide CHECK_INCOMPLETE and then map to a result that does not automatically allow.

Project structure

biz-guard/
├── src/bizguard/        # 核心：规则、决策、图谱、检索、CLI 与 CI
├── agents_mcp/          # MCP 协议适配层，供 AI 编程助手调用
├── fixtures/            # 三个脱敏 Java 微服务 fixture 与辅助编译脚本
├── sample/              # Python 示例代码与可复现的 diff
├── policy/              # 业务不变量与策略注册表
├── registry/            # 领域契约登记数据
├── knowledge/           # 已发布知识、ADR 与检索素材
├── bench/               # 黄金基准、决策 fixture、五组消融任务
├── tests/               # 自动化测试
├── scripts/             # Demo、安装验证和 benchmark 脚本
└── docs/                # 架构决策记录

Demo: the same change, two different results

From the project root, run:

./scripts/demo.sh

The script will demonstrate a "native Coding Agent comparison group" (an offline, deterministic, scripted baseline) that considers the change plausible and passes it; then BizGuard checks the same diff and returns BLOCKED. This is not a measurement of the native capabilities of Claude Code or Codex; a real Agent runs only when the benchmark is in --live mode and a real Agent command is configured.

You can also directly look at a violation example:

bizguard check --diff sample/diffs/diff_violation_1.diff

The diff removes IdempotencyStore.check(idempotency_key). BizGuard will output BLOCK and return the removed the idempotency check as a finding/evidence, so you can trace back why the change is blocked, not just get a black-box "failed".

Quick Start

Environment Requirements

• Python 3.12+

• Java 17 (for compiling/verifying Java fixtures)

git clone https://github.com/PureBlueFrank/biz-guard.git
cd biz-guard

# 常规安装
pip install -e .

# 运行当前工作区的全部测试（当前可收集 259 个）
pytest

In an offline environment first prepare the build dependency hatchling in a virtual environment or internal package source, then use:

pip install --no-build-isolation -e .

pip install -e . will, by default, try to create an isolated build environment, which may attempt to download hatchling when offline.

Common CLI

The following commands assume that your current directory is the project root. prepare requires you to provide the task, and the involved repositories / base version; impact works on the impact graph and returns paths and evidence.

# 编译 Agent 可读的上下文包
bizguard prepare --task "检查优惠券状态字段变更" \
  --repos coupon-core coupon-contract \
  --base-revisions bench/fixtures/phase3-revisions.yaml --json

# 检查 unified diff 是否违反 Policy
bizguard check --diff sample/diffs/diff_violation_1.diff

# 分析跨服务影响
bizguard impact analyze \
  --diff bench/fixtures/phase3/dto-status.diff \
  --repos fixtures/java-microservices \
  --revision-set bench/fixtures/phase3-revisions.yaml --format json

# 搜索受治理的团队知识
bizguard knowledge search --query "优惠券核销必须使用幂等键" \
  --scope coupon_redemption --revision semantic-seed-v1 \
  --roles engineering --json

8 MCP Tools

MCP (Model Context Protocol) is the standard interface that lets AI assistants call external capabilities. BizGuard provides the following 8 tools:

1. prepare_change: build a read-only Context Pack;

2. search_team_knowledge: search the team knowledge that you have access to;

3. explain_symbol: explain the indexed symbol and its graph evidence;

4. analyze_impact: analyze impact paths, unknown boundaries, and must-test items;

5. validate_patch: deterministic validation of a combined diff;

6. get_required_tests: find the tests that need to run per Policy;

7. request_approval: currently provides only an approval schema, it will not create an approval record;

8. get_change_decision: returns the four-state aggregated decision, evidence, tests, and approver.

Install a closed-loop check

./scripts/verify_install.sh --offline

This script checks the local run and CI slow check, and the default uses the cross-service DTO change fixture.

Honest statement and limitations

• BizGuard is an open-source proof-of-concept project, not a well-tested system ready for production guard raining.

• Java support only covers the three de-identified fixture repositories, not a full Java ecosystem analyzer.

• The offline benchmark's Agent track is a scripted/heuristic baseline; only when run with --live and a real Agent command configured will it actually run a real Agent.

• The desired embedding model is Zhipu's embedding-3; offline it falls back to lexical search and marks the degradation explicitly. This is suitable for development and demos; it should not be treated as equivalent to the real embedding for production acceptance.

• A diff protected by a policy will be applied in memory to the current fixture baseline before AST yes/on; the workspace datasource will not be modified. If the diff cannot be applied, or the policy does not cover it, the system will not guess that it is safe.

Contributions and feedback

We welcome you to read the contributing guidelines, and discuss new invariants, fixtures, and odd issues via issue or PR.