Bce

BCE — diagnose, repair, and prove architecture conformance

BCE is a fail-closed architecture-conformance gate. A blueprint is policy; source code is the normal repair surface. Prefer the repository's BCE MCP server for diagnosis and working-tree verification. Use the CLI only when MCP is unavailable or the requested lifecycle operation is intentionally absent from MCP.

For first adoption, use the current coding agent's reasoning and author to draft one supported boundary from stated intent. An additional provider call is optional. Resolve bundled references under the installed node_modules/bce-engine/docs/ and spec/, not the consumer's own docs/.

Choose the shortest workflow

• Existing repository is red: follow the MCP-first repair loop below. Do not load lifecycle authoring material.
• Readiness or setup looks broken: call doctor_repository {} before the gate.
• A blueprint or gate may be vacuous: call validate_blueprint, then assess_teeth.
• The user asks to inspect or compare policy: call inspect_blueprint, explain_constraint, or compare_blueprint_policy; replay supplied evidence with verify_review_packet.
• The user asks to create or adopt a new rule: read references/lifecycle.md before acting. Use local bce author, or the optional bce propose adapter; governance changes use the CLI and require an authenticated human review.
• The user asks to tune an Agent Skill: use the separate skill-tuning skill.

MCP-first repair loop

1. Call run_gate {}. The generated server starts in the repository, so omit repoDir unless the user deliberately targets another tree.
2. Read structured fields, not the process exit alone:
   • gateFailed: true, outcome: "violation", or a report verdict: "fail" is RED;
   • outcome: "refusal" is RED and must not be routed around;
   • advisory mode may return exitCode: 0 while the substantive verdict is still RED.
3. Use each violation's constraintId, evidenceRef, observed, and expected to identify the smallest source-code correction.
4. Change code, not policy. Do not edit blueprints, baselines, mode, waivers, workflows, MCP config, installed skills, or engine pins merely to clear a violation.
5. Call run_gate {} again against the live working tree. Finish only when gateFailed is false, outcome is pass, and every selected report passes.
6. Report the exact violation fixed, changed code files, final score/verdict, and whether policy changed. A normal repair must say policy did not change.

The MCP server exposes ten read-only tools:

MCP cannot generate a proposal, record a decision, ratify, amend, graduate, create a baseline, or weaken policy. That absence is a security boundary, not missing functionality.

CLI fallback

If the project has no working BCE MCP server, use the exact local package rather than fetching a moving version:

npx --no-install bce gate --repo . --extractor ast --all

For an uncommitted repair, gate already scans the live tree. If you intentionally run one blueprint directly, add --no-pin; otherwise run grades committed HEAD by default:

npx --no-install bce run --blueprint <path> --ct-repo . --no-pin --extractor ast --out compliance-report.json

Exit 0 is a process pass only after reading advisory state and the report verdict. Exit 1 is a graded violation or usage/configuration error; exit 2 is a fail-closed scan/refusal condition. Treat 1 and 2 as RED.

Policy boundary

The following are governed surfaces: .blueprints/**, .bce-mode.json, baseline and waiver files, the BCE workflow, agent/MCP configuration, installed skills, and engine pins. Do not change one as an incidental repair. If the contract itself is wrong, stop and propose a separate reviewed policy change with rationale.

Never:

• lower a threshold, grow a baseline, or narrow scope just to obtain green;
• interpret advisory exit 0 as conformance when reports still fail;
• claim a constraint works without a discriminating RED;
• report evaluator-refutable as extractor-real teeth;
• treat a structural refusal as a pass;
• claim an agent-operated run is independent-human evidence.

Authoring and adoption

Only load references/lifecycle.md when the task is to create, validate, prove, onboard, ratify, or operate a contract. It contains the constraint grammar, extraction profiles, exact commands, advisory/baseline/graduation path, and CI invariants.

Use the repository's existing package manager: pnpm exec bce or yarn bce replaces the npm runner. Do not fetch a package named bce, silently change package managers, or require a global install.

Prefer local, version-matched package documentation. The v0.3.1 package includes spec/SPEC.md, offline review prepare, and solo-steward ratification. Use the installed local binary for those commands; a source checkout is not required. The immutable npm 0.3.0 tarball lacks those additions and omits spec/SPEC.md; when operating that version, use https://github.com/blueprint-conformance/bce/blob/v0.3.0/spec/SPEC.md if the local file is absent. Identify the existing artifact before installing anything. The current exact registry target is bce-engine@0.3.1; run npm view bce-engine@0.3.1 version dist.integrity and verify its release record before changing the selected artifact. Check the separately selected CI engine too; upgrading locally does not update an existing workflow.