bce

# bce — the blueprint conformance engine

> A local, fail-closed architecture-conformance gate operated by coding agents. The current agent
> authors a draft, runs the gate, diagnoses violations, and repairs code. An authenticated human
> owns architectural intent and decides whether an exact review packet may enter the policy ceremony.
> The resulting blueprint is a durable
> architectural contract for a repository; bce measures the code against it and produces a
> deterministic conformance score, a fail-closed required-check gate for merges, and hash-chained
> evidence anyone can re-derive offline. TypeScript/JavaScript framework AST extraction is the
> mature released path. The v0.3.0 release introduced direct TypeScript/JavaScript and structured Python
> module graphs while preserving the Python import-surface profile. The immutable registry release
> is v0.6.2; it adds npm identification on Windows when emitting evidence and a production-only
> published `npm-shrinkwrap.json`, and retains v0.6.1's architecture review, policy-impact preview,
> repair briefs, workspace-aware stack review and the bounded `forbiddenDependencyPath` arm
> (minEngineVersion 0.6.1), plus the v0.5.0 declared package/image/runtime contracts, expanded route
> inventory, offline review preparation and solo-steward lifecycle support.
> Route evidence remains call-site presence, with authorization behavior unverified. The npm integrity is
> `sha512-ld3LEyKp6o5hxVDxfgjH6KnKHmKXGFHZwZhcXONb5WtCSs4dAtCSR/ep2s7OXlvAe9IkqKIdOFPvvjaUQJWN5A==`;
> verify registry metadata before installation. Compatibility remains pre-1.0.

Core rules for an agent working in a bce-gated repo: (1) the gate is the done-check — a change is not
done until `bce gate` is green; (2) on a red, fix the code, never silently edit the blueprint; (3) the
baseline only ever shrinks — accepting a new violation is a reviewed human decision; (4) fail-closed,
no skip flags — a refusal is a red, not a pass.

## Start here

- [Agent start guide](docs/agent-start.md): choose existing-gate repair, new-repository adoption, human inspection, or contribution; use the current coding agent without requiring a second model account.
- [Quickstart (offline RED→fix→GREEN)](examples/quickstart/README.md): the guaranteed path, no API keys, five minutes.
- [Quickstart summary](docs/quickstart.md): the one-screen version.
- [Executable recipe catalog](docs/first-win.md): install v0.6.2, run `npx --no-install bce demo --list`, then a real GREEN/named-RED proof for extension contracts, tenant route guards, governed egress, TypeScript or Python module layering, or configuration allowlists.
- [Authoring matrix](examples/first-win/README.md): adapt a recipe to one of six starting layouts (empty repo, plain JavaScript, TypeScript, monorepo, TypeScript layering, Python layering); each `bce author` loop is timed under 120s in CI.
- [README](README.md): what bce is, in a paragraph.
- [AI-first proposal and review](docs/ai-first-review.md): bounded disclosure, draft-only generation,
  deterministic packets, GitHub-bound decisions, and attended landing.

## Adoption

- [Adopt on an existing repo](docs/adopt-existing-repo.md): the ladder — advisory → baseline → graduate → enforced; the honest brownfield story.
- [FAQ](docs/faq.md): why baseline is not a bypass; why there is no skip flag.
- [Run bce in an agent loop](docs/agent-loop.md): per-harness (Claude Code / Cursor / generic MCP); the violation→fix→re-gate loop.
- [Integration snippets](integrations/README.md): drop-in CLAUDE.md / AGENTS.md / .cursorrules blocks + the MCP tools.
- [Agent Skill](skills/README.md): proposal/review plus validate → run → teeth → gate as a loadable skill; copy `skills/bce` into `.claude/skills/`.
- [BCE skill instructions](skills/bce/SKILL.md): load the operating instructions directly; preserve policy and read the structured gate result.
- [Authoring and adoption reference](skills/bce/references/lifecycle.md): load only for a new boundary or a governed policy task; local authoring needs no second model account.

## Reference

- [Specification](spec/SPEC.md): normative — artifact model, 11-type constraint taxonomy, scoring, modes, versioning.
- [Visual guide to C1–C4](docs/constraint-guide.md): diagram-led explanation of required components, required edges, forbidden imports, and forbidden component paths.
- [TypeScript module graph](docs/typescript-module-graph.md): direct-boundary selectors, deterministic resolution, unresolved-import behavior, and explicit non-goals.
- [Python module graph](docs/python-module-graph.md): structured direct imports, explicit roots, fail-closed uncertainty, and explicit non-goals.
- [Exit codes](docs/exit-codes.md): 0 = command success (advisory may still be RED), 1 = violation/user-error, 2 = fail-closed refusal; read the structured verdict.
- [Report contract](docs/report-contract.md): the deterministic compliance report; determinism and canonical serialization.
- [Evidence format](docs/evidence-format.md): the hash-chained evidence record + the zero-dependency verifier.
- [Public evidence](research/model-evaluation/pilots/accelerated-v6/RESULTS.md): the completed v6 directional instrumentation record, its explicit claim boundary, and `npm run evidence:verify` replay command.
- [Published schemas](spec/schemas): generated JSON Schemas (draft-07).
- [Conformance vectors](spec/conformance-vectors/README.md): input→expected-verdict data (no runner, no levels at v1alpha1).

## Proposing and authoring blueprints

- [Ordered onboarding](docs/onboarding.md): preferred current-agent authoring path with no second model account.
- [AI-first proposal and review](docs/ai-first-review.md): optional provider-backed proposal with bounded disclosure and one immutable review packet.
- [Blueprint-author prompt pack](prompts/blueprint-author.md): drive an agent to draft a blueprint from an existing repo; always ends in `bce teeth` + human review.
- [Prompt-pack validation](prompts/VALIDATION.md): the 5-public-repo acceptance runs.

## The engine gates itself

- [Live self-adoption](docs/live-self-adoption.md): read the GitHub-backed main-commit pipeline, its refresh behavior, authenticated records, and evidence boundaries.
- [Self-hosting](docs/self-hosting.md): bce gates its own tree; Lane A/B, the bootstrap-0 exception, the Lane-A pin ceremony, the admin-override incident policy.
- [Corpus map](corpus/CORPUS-MAP.md): the seeded-defect corpus (recall denominator) and its relation to the paper corpus.
- [This repo's blueprint](.blueprints/engine.blueprint.json): the contract the self-gate enforces.

## Project

- [Current release verification](docs/release-v0.6.2.md): exact npm/source identities, signed release assets, installed consumer checks, and explicit limits.

- [Contributing](CONTRIBUTING.md): DCO sign-off, agent-authored-PR conventions, the violation-message style guide.
- [Governance](GOVERNANCE.md): solo maintainer, AI-driven operations, no board, no SLA, Apache-2.0 open core.
- [Maintainer operations](docs/maintainer-operations.md): intent-shaped intake, canonical queue labels, the read-only 168-hour response audit, and the no-phantom-review boundary.
- [RFC process](rfcs/RFC-0001-process.md): how the format changes — the widen-only ratchet.
- [Security policy](SECURITY.md): private vulnerability reporting.
- [Working on bce itself](AGENTS.md): the repository map for an agent contributing to the engine.

## Films

- [Film library](docs/films.md): Context-spectrum interaction, reference architecture and historical agent-fleet films; explicit provenance boundaries and downloadable originals.

- Paper working draft: https://blueprint-conformance.github.io/bce/paper/