How Configuration Key Ownership and Documentation Inheritance Work in no-mistakes

no-mistakes treats every configuration option as a first-class fact with a single authoritative documentation source, using a shallow merge strategy where repository-specific settings in .no-mistakes.yaml override global defaults from ~/.no-mistakes/config.yaml while preserving documentation ownership.

The no-mistakes configuration system enforces strict configuration key ownership to prevent documentation drift and implementation inconsistencies. Each setting exists as a first-class fact tied to a specific documentation file, ensuring that definitions, types, and defaults remain synchronized across the codebase. This design combines explicit ownership rules with a hierarchical inheritance model that lets repositories customize behavior without duplicating entire configuration schemas.

Understanding Configuration Key Ownership

Global Configuration Keys

Global keys residing in ~/.no-mistakes/config.yaml are owned by docs/reference/global-config.md (located at docs/src/content/docs/reference/global-config.md). This file serves as the master reference for all global configuration keys, defining their defaults, types, and descriptions as implemented in internal/config/config.go.

Repository-Specific Keys

Per-repository settings in .no-mistakes.yaml files are owned by docs/reference/repo-config.md (at docs/src/content/docs/reference/repo-config.md). When a repository provides its own configuration, the daemon loads the trusted default-branch copy of that file to apply overrides, ensuring that changes undergo proper review before affecting runtime behavior.

Environment Variables

Environment-based configuration is owned by docs/reference/environment.md (at docs/src/content/docs/reference/environment.md), which catalogs all environment variables affecting the daemon and client behavior according to the source definitions in internal/config/config.go.

Enforcement Through Drift Tests

The ownership rule is enforced by comment blocks and CI drift tests that validate synchronization between documentation and the struct definitions in internal/config/config.go. If a new key is added without updating the corresponding documentation file, the CI pipeline fails, preventing documentation rot.

How Configuration Inheritance Works

The Shallow Merge Strategy

Inheritance operates through a shallow merge that preserves the documentation ownership hierarchy. The system starts with global defaults, then applies repository-specific overrides for only the fields explicitly set in the repo config. Unspecified keys automatically inherit global values, maintaining their original documentation sources.

Loading Order and Precedence

The loading sequence follows three distinct steps:

1. Load global defaults from ~/.no-mistakes/config.yaml
2. Load the default-branch copy of .no-mistakes.yaml from the repository
3. Merge the repository configuration on top of global defaults using shallow key replacement

Practical Configuration Example

Consider the following global configuration:

# ~/.no-mistakes/config.yaml (owned by docs/reference/global-config.md)

agent: auto
auto_fix:
  rebase: 3
  review: 0
  test: 3
  lint: 3

A repository can override specific values without redefining the entire schema:

# .no-mistakes.yaml (owned by docs/reference/repo-config.md)

auto_fix:
  rebase: 1
agent: codex

The resulting merged configuration preserves inherited values while applying overrides:

agent: codex          # From repo config

auto_fix:
  rebase: 1           # From repo config

  review: 0           # Inherited from global

  test: 3             # Inherited from global

  lint: 3             # Inherited from global

Source Files and Documentation Hierarchy

The following files implement and document the ownership model:

• internal/config/config.go: Contains struct definitions and loading logic for global and repository configurations.
• docs/src/content/docs/reference/global-config.md: Master reference and owner of all global configuration keys.
• docs/src/content/docs/reference/repo-config.md: Reference and owner of per-repository configuration overrides.
• docs/src/content/docs/reference/environment.md: Reference and owner of environment variables affecting the daemon.
• AGENTS.md (repository root): Documents high-level ownership conventions across the codebase.

Summary

• Configuration key ownership assigns each setting to a specific documentation file, preventing drift between code and docs.
• Global keys reside in ~/.no-mistakes/config.yaml and are owned by docs/reference/global-config.md.
• Repository keys in .no-mistakes.yaml are owned by docs/reference/repo-config.md.
• Shallow merge inheritance applies repo overrides atop global defaults without requiring schema duplication.
• Drift tests in CI enforce that internal/config/config.go structs remain synchronized with their documentation owners.

Frequently Asked Questions

What happens if a repository doesn't define a .no-mistakes.yaml file?

If no repository-specific configuration exists, the system uses only the global defaults from ~/.no-mistakes/config.yaml. All settings inherit their values and documentation from the global configuration owner without requiring an empty configuration file.

How does no-mistakes prevent documentation from becoming outdated?

The codebase includes drift tests that compare struct definitions in internal/config/config.go against the owned documentation files. CI fails if a configuration key exists in code but lacks corresponding documentation updates in the assigned reference file, ensuring single-source-of-truth maintenance.

Can environment variables override repository configuration values?

Yes, environment variables documented in docs/src/content/docs/reference/environment.md can affect daemon and client behavior. The inheritance hierarchy typically resolves such that explicit file-based configurations combine with environment overrides according to the specific loading implementation in internal/config/config.go.

Why does the system load the default-branch copy of the repo config?

Loading the trusted default-branch version of .no-mistakes.yaml ensures that configuration changes undergo proper review through the version control workflow before affecting the daemon's behavior. This prevents unreviewed local modifications from impacting operations while maintaining the integrity of the ownership model.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}