Check architectural boundaries in agent-written code

bce gives coding agents a local, deterministic architecture check. A versioned EngineeringBlueprint records the repository's structural rules. Agents draft those rules from your intent, inspect the code, and repair violations; the same engine checks every pull request. Humans own the intent and approve policy changes. Agents operate the day-to-day loop.

Released support (v0.3.0): TypeScript/JavaScript framework-surface AST extraction, direct TypeScript/JavaScript module boundaries, a Python import-surface MVP, and structured Python module boundaries. Node 22+ is required; the contract remains pre-1.0.

Evidence boundary: a score of 100 means the implemented checks passed over the observed surface. Route guard checks find governed call sites; they do not prove authorization, tenant isolation, or execution on every path. See the route evidence limits and correction, including the export forms missed by the immutable v0.3.0 release. Start with a bounded pilot and verify realistic violations in your own repository.

Watch BCE govern its own main branch: live GitHub stages, authenticated self-adoption, and explicit evidence boundaries.

Watch the context move

Explore the interactive C1–C4 spectrum · Watch the films · Read the static overview

Follow context narrowing into work, inherited rules surviving the zoom, and findings returning as evidence for review. This illustrates the wider reference architecture; it is not a claim that the complete platform loop is released in BCE. C1–C4 here means architectural zoom levels, distinct from the engine’s constraint type identifiers. The brief preview plays once; the full film and interactive experience have playback controls.

Start with your coding agent

Give your existing agent this task:

Read https://blueprint-conformance.github.io/bce/llms.txt and its agent start guide.
Inspect this repository and identify one supported architecture boundary from our stated intent.
Use BCE to draft the rule, prove a real RED → code fix → GREEN, and wire the local agent loop.
Keep setup advisory and present policy changes for my review. Report unsupported scope explicitly.

The agent start guide routes an existing gated repository straight to MCP run_gate {} and a new repository to local authoring and onboarding. Your current agent can do this with its own tools; BCE needs no additional model account for that path. The blueprint inspection tools and review cockpit let humans examine the same contract and evidence.

Run a real gate

Three commands. No account, hosted service, API key, or repository setup:

npm view [email protected] version dist.integrity
npm install --save-dev --save-exact [email protected]
npx --no-install bce demo

The released demo runs one conforming tree and one drifted tree. List six targeted recipes for extension registration, tenant access, egress, TypeScript and Python module layering, and configuration widening, then run the boundary closest to your repository:

npx --no-install bce demo --list
npx --no-install bce demo --recipe module-layering

Run the released First Win recipes, or keep the zero-argument proof above.

The architecture package

One checked-in blueprint defines the intended components, relationships, and boundaries. BCE extracts the repository it received, compares the two, and returns one deterministic verdict.

These are the specification's first four enforcing types: C1 requiredComponent requires a real pluginSurface; C2 requiredDependency requires its governed registration edge; C3 forbiddenDependency rejects the axios import; and C4 forbiddenPath keeps extracted components out of src/legacy/**. The taxonomy has four more enforcing types and three explicit reserved types—open the C1–C4 visual guide or read the exact semantics.

In v0.3.0, the AI-first review surface's bce propose writes an immutable draft packet to quarantine; the model cannot approve or land policy. Read the review ceremony.

See the gate discriminate

This excerpt is cut from a live engine run on every push. It keeps the decisive lines selectable while the full transcript retains every emitted detail.

$ bce gate --repo drift --blueprint-dir blueprint --extractor ast --all
::error::    - [no-direct-http-client/critical] extension:greeting.plugin
        observed: forbidden edge extension:greeting.plugin -> axios is present
        at:       src/greeting.plugin.ts#L16
bce gate [enforced]: 1/1 blueprint(s) evaluated, 1 failing.
$ echo $?
1

$ bce gate --repo clean --blueprint-dir blueprint --extractor ast
  ✓ [email protected] — score 100 (pass)
bce gate [enforced]: 1/1 blueprint(s) evaluated, 0 failing.
$ echo $?
0

CI derives those lines from real RED and GREEN runs and rejects byte drift. The proof contract also verifies the complete recording and visual replay against the engine.

One engine, three entry points

Use the CLI for local feedback, the pinned GitHub Action at the merge boundary, or ten read-only MCP tools inside an agent loop. They share the same extraction, evaluation, report, and exit-code path; policy changes remain outside MCP. The released Action source is pinned to blueprint-conformance/bce@9fe4a02d39c05dbdf280b359e9b364de84e1eda8.

The Agent Skill loads these instructions on demand, prefers the read-only run_gate {} tool, fixes source code on RED, and re-runs the same contract. Inspect the skill, wire the done-check, or follow ordered onboarding.

Adopt without freezing the repository

Start in advisory mode, capture known debt in a shrink-only baseline, then enforce the same verdict. The mode is committed policy—not a skip flag—and moving backward requires a reviewed rationale. Read the brownfield adoption guide.

Evidence and limits

Mechanism evidence is strong; causal product benefit is not established. This repository has a generated suite whose current count is shown above, replayed RED/GREEN fixtures, 47/47 killed self-blueprint mutants, deterministic reports, and cross-platform CI. Those are first-party proofs on author-controlled infrastructure; independent witnesses remain 0.

Accelerated pilot v6 retained all 16 paired attempts in one exact local model/client cell. Its author-operated record contains useful directional observations, including 2/8 versus 3/8 safe successful completions, but it is permanently ineligible for a product decision. One baseline infrastructure timeout remains in the intention-to-treat denominator. The Evidence Foundry v3 primary stage—120 paired tasks and 240 retained attempts—has not run; its later transport stages are separately gated. We do not claim that BCE makes agents more successful, cheaper, faster, or safer than a baseline. Inspect and replay the public evidence, check the public truth ledger, or inspect the study contract.

Start with your repository

The v0.3.0 release contains six packaged architecture recipes. Run one, then adapt it with a measured authoring walkthrough for an empty repository, plain JavaScript, TypeScript, a monorepo, or direct module layering: choose the boundary that must hold. The measured test keeps every layout's author → RED → fix → GREEN first win in under 60 seconds, including loaded-runner contention.

Specification: blueprint-conformance/v1alpha1 · Agent loop: MCP and agent workflow · Documentation: blueprint-conformance.github.io/bce

Source candidate: v0.3.1. This stages the route-inventory correction and makes its call-site evidence limit visible in the terminal. The registry release remains v0.3.0 until the candidate passes the release workflow and the published artifact is verified. Check availability before choosing an install target:

npm view [email protected] version dist.integrity

The v0.3.1 candidate also packages the previously merged offline review preparation, explicit solo-steward lifecycle, and local specification; these remain absent from immutable v0.3.0.

Current registry release: v0.3.0. Its exact npm integrity is sha512-KwWyEYOZu70xrQG5JYEyHNhz3eqTalno9d9+KUugytYBiWtHGO7Wpa+X/7xgi9xDc49V7OUchTJtN8Pu8T37iw==, and its source/Action commit is 9fe4a02d39c05dbdf280b359e9b364de84e1eda8. The canonical GitHub Release is immutable with the exact tarball, signed payload manifest, signed EvidenceRecord, and compliance report attached. Read the verification and incident record. Compatibility remains pre-1.0.

Apache-2.0 — license, notice, and trademarks.