Pillar — Build & Environment

Prefix: BLD- What it measures: whether an agent can reproduce the build and bootstrap a fresh environment from main without a human walking it through the process — pinned runtimes, committed lockfiles, environment templates, devcontainers, hermetic CI, and published Docker images.

Each of these removes an avenue of environment drift. Representative criteria cover pinned runtime versions, committed lockfiles, devcontainer or equivalent environment definition, and deterministic build output.

Criteria in this pillar

BLD-010 — Reproducible build

Level: 1 · Scope: application · Check: deterministic
pnpm build (or equivalent) succeeds without warnings on a clean clone and produces consistent output given the same inputs.
Rationale: a broken or nondeterministic build blocks every agent task downstream.
Evidence expected: build command defined; green build on CI; no warnings.

BLD-020 — Node / runtime version pinned

Level: 2 · Scope: repository · Check: deterministic
.nvmrc / .tool-versions / pyproject.toml.tool.python.requires / go.mod.go pins the runtime version. For Node, package.json.engines.node matches.
Rationale: version drift causes "works on my machine" bugs that agents cannot reproduce.
Evidence expected: pin file present; constraint narrow (e.g., >=22 <23).

BLD-030 — Lockfile committed

Level: 1 · Scope: repository · Check: deterministic
pnpm-lock.yaml / poetry.lock / Cargo.lock / go.sum is committed.
Rationale: without a lockfile, dependency resolution is nondeterministic and bugs become unreproducible.
Evidence expected: lockfile present; not in .gitignore.

BLD-040 — `.env.example` documents every env var

Level: 2 · Scope: application · Check: deterministic
A committed .env.example lists every env variable the application consumes, with placeholder values.
Rationale: agents setting up a fresh environment need a complete, authoritative list — not archaeology across the codebase.
Evidence expected: .env.example present; count of vars ≥ count of process.env.* references in source.

BLD-050 — Local-setup script or devcontainer

Level: 3 · Scope: application · Check: deterministic
A .devcontainer/devcontainer.json exists, OR a documented scripts/setup.sh takes a fresh clone to a working local environment in one command.
Rationale: agents in fresh environments cannot ask "how do I get this running"; they need a reproducible path.
Evidence expected: devcontainer config or setup script; documentation linking to it.

BLD-060 — Hermetic CI (no network for test/build beyond cache)

Level: 4 · Scope: application · Check: manual
CI jobs declare their dependencies explicitly; no curl | bash steps; lockfile- based installs only; network egress reviewed.
Rationale: hermeticity removes a class of CI flake that masks real test failures.
Evidence expected: CI workflow review; absence of curl | bash or untracked download steps.

BLD-070 — Docker image produced and published

Level: 4 · Scope: application · Check: deterministic
A Dockerfile builds a working image; CI publishes it to a registry on release.
Rationale: portable runtime artifacts let agents reproduce the production environment locally.
Evidence expected: Dockerfile present; release workflow includes image publish step.

The 8 pillars — sibling pillars in v1.0.
Criteria catalog — all criteria, one page.
Maturity levels — how criteria combine into a level.

Criteria in this pillar

Level: 1 · Scope: application · Check: deterministic

pnpm build (or equivalent) succeeds without warnings on a clean clone and produces consistent output given the same inputs.

Rationale: a broken or nondeterministic build blocks every agent task downstream.

Evidence expected: build command defined; green build on CI; no warnings.

Level: 2 · Scope: repository · Check: deterministic

.nvmrc / .tool-versions / pyproject.toml.tool.python.requires / go.mod.go pins the runtime version. For Node, package.json.engines.node matches.

Rationale: version drift causes "works on my machine" bugs that agents cannot reproduce.

Evidence expected: pin file present; constraint narrow (e.g., >=22 <23).

Level: 1 · Scope: repository · Check: deterministic

pnpm-lock.yaml / poetry.lock / Cargo.lock / go.sum is committed.

Rationale: without a lockfile, dependency resolution is nondeterministic and bugs become unreproducible.

Evidence expected: lockfile present; not in .gitignore.

Level: 2 · Scope: application · Check: deterministic

A committed .env.example lists every env variable the application consumes, with placeholder values.

Rationale: agents setting up a fresh environment need a complete, authoritative list — not archaeology across the codebase.

Evidence expected: .env.example present; count of vars ≥ count of process.env.* references in source.

Level: 3 · Scope: application · Check: deterministic

A .devcontainer/devcontainer.json exists, OR a documented scripts/setup.sh takes a fresh clone to a working local environment in one command.

Rationale: agents in fresh environments cannot ask "how do I get this running"; they need a reproducible path.

Evidence expected: devcontainer config or setup script; documentation linking to it.

Level: 4 · Scope: application · Check: manual

CI jobs declare their dependencies explicitly; no curl | bash steps; lockfile- based installs only; network egress reviewed.

Rationale: hermeticity removes a class of CI flake that masks real test failures.

Evidence expected: CI workflow review; absence of curl | bash or untracked download steps.

Level: 4 · Scope: application · Check: deterministic

A Dockerfile builds a working image; CI publishes it to a registry on release.

Rationale: portable runtime artifacts let agents reproduce the production environment locally.

Evidence expected: Dockerfile present; release workflow includes image publish step.