Why this rule
An agent that cannot reproduce the project’s toolchain installs the wrong version, runs tests against the wrong runtime, and produces fixes that pass locally but break in CI or on a colleague’s machine. Reproducibility is not just a developer convenience — it is the foundation of an agent’s ability to self-verify. Without a pinned, committed toolchain, the agent’s environment is undefined. A fix that works in one environment may silently fail in another.What triggers it
Charter checks three things independently. Any one of them can fire the finding: 1. Missing toolchain declaration — No pinned runtime file exists for an active language. 2. Missing lockfile — A language that produces a lockfile has not committed one. 3. Missing hook manager config — No hook manager configuration is committed to the repo, so pre-commit enforcement is local-only and cannot be verified by an agent or reproduced in CI.Accepted toolchain declarations
Accepted toolchain declarations
Charter recognizes the following files as valid toolchain declarations:
| Scope | Accepted files |
|---|---|
| Universal | mise.toml, .mise.toml, .tool-versions, devcontainer.json, flake.nix |
| Go | go.mod with a toolchain directive |
| JavaScript / TypeScript | .nvmrc, .node-version, bunfig.toml, package.json#volta |
| Python | pyproject.toml with requires-python |
| Rust | rust-toolchain.toml |
| Swift | .swift-version |
| Kotlin / JVM | gradle-wrapper.properties |
| Ruby | .ruby-version |
Accepted lockfiles
Accepted lockfiles
| Language | Lockfile |
|---|---|
| Go | go.sum |
| JavaScript (npm) | package-lock.json |
| JavaScript (yarn) | yarn.lock |
| JavaScript (pnpm) | pnpm-lock.yaml |
| Rust | Cargo.lock |
| Python (uv) | uv.lock |
| Python (pip) | requirements.txt pinned with exact versions |
Accepted hook manager configs
Accepted hook manager configs
| Hook manager | Config file |
|---|---|
| hk | hk.pkl |
| husky | Any file under .husky/ |
| lefthook | lefthook.yml |
| pre-commit | .pre-commit-config.yaml |
Examples
- Failing
- Passing
A Node.js repo with
package.json but no .nvmrc, no engines field, and no package-lock.json committed — the runtime is floating and the dependency graph is not reproducible.A Go repo with go.mod but no go.sum committed — the lockfile is missing.A repo with CI and tests but no committed hook manager config — local hook behavior is unverifiable.How to fix
- mise (recommended)
- Language-native
mise is a universal version manager that covers every language in a single file:mise.toml
mise install to generate mise.lock, then commit both files. Add mise install to your onboarding docs.Score impact
Medium (−4); no hard cap. Each sub-check (toolchain, lockfile, hook config) is a separate finding instance, so a repo missing all three can incur −12 points from this rule alone.
Edge cases
Partial language coverage
Partial language coverage
Partial language coverage is acceptable only if the uncovered language is not active in the repo. See AE-TEST-001 for how Charter determines whether a language is active.
Local-only helper scripts
Local-only helper scripts
Local-only helper scripts do not satisfy reproducibility for tracked task config. The toolchain declaration and lockfile must be committed to the repo.
Related rules
AE-CI-002
Requires Charter to run in CI so the reproducible environment is verified on every PR.
AE-AUTO-001
Requires a discoverable test command — meaningless without a reproducible runtime.