AGENTS.md — working in this repository

This file orients a coding agent (or a human) working on bce itself. If you are instead looking for the snippet to drop into another repo so an agent treats bce as its done-check, that is integrations/AGENTS.md.snippet.

What this repository is

bce, the blueprint conformance engine — a fail-closed architecture-conformance gate. You author an EngineeringBlueprint (a durable architectural contract for a repository), and bce measures the code against it: a deterministic conformance score, a fail-closed required-check gate, and hash-chained evidence anyone can re-derive offline. TypeScript/JavaScript framework AST extraction is the mature released path; the current v0.6.2 release retains (from earlier releases) direct TypeScript/JavaScript and structured Python module graphs behind the same language-neutral provider seam, plus declared-stack enforcement over selected package, image, and Node declarations.

The rules that never bend

1. The gate is the done-check. A change is not done until bce gate is green. A green typecheck or test run is necessary but not sufficient.
2. On a red, fix the code — never silently edit a blueprint or the baseline. The blueprint is the contract; the baseline only ever shrinks. Changing either is a deliberate, separately-reviewed act.
3. Fail-closed, no skip flags. There is no --skip / --no-verify / --force. If the engine cannot honestly grade, it refuses (exit 2) — treat a refusal as a red, never a pass. Adoption is handled by committed config (advisory mode, shrink-only baseline), never an invisible flag.
4. Nothing internal leaks. A dependency-free leakage-gate runs from commit #1 and rejects any internal identifier, host, or credential-shaped string. Keep it green.
5. Describe only machinery that runs. Every workflow, script, and path this repo's docs name must exist or be explicitly marked as a forward/deferred item. No fictional pipelines.

Map of the repository

Build, test, gate (Node 22 toolchain)

npm ci            # clean, lockfile-exact install
npm run build     # tsup + declaration emit → dist/
npm run typecheck # tsc --noEmit, full tree
npm test          # the full vitest suite
node dist/cli.js gate --repo . --repo-name blueprint-conformance/bce   # gate this repo

Before you claim a change is done, all required PR checks must be green. For release or public-site work, also wait for all release-relevant post-merge workflows and all six portability legs on the exact merged main commit; a passing PR or Pages deployment is not completed release verification. See the portability contract and CONTRIBUTING.md for the DCO sign-off and agent-authored-PR conventions (gate green + evidence ref in the PR body), and docs/self-hosting.md for the self-gate and the admin-override incident policy.

Machine-readable index

llms.txt is the compact, link-first index of this repository for an agent that prefers a flat map. It points at the same documents as the table above.

Self-adoption integration

Project skills are installed under .agents/skills/ from the canonical skills/ tree. Run node scripts/sync-self-agent-skills.mjs after editing a canonical skill; CI checks freshness. Build first, then the project MCP configuration runs node dist/mcp-server.js from this checkout. Use MCP run_gate {} as the live-tree done-check, or node dist/cli.js gate --repo .. Review .bce-governance.json for the explicit solo-steward authority. A self-ratified decision claims no independent review. Changes to policy, agent configuration, or installed skills require the human owner's review.