# Development Start here when contributing to ConfigKit. Read the task-specific owners below before making changes. The [component overview](internal/overview.md) maps implementation responsibilities; the [configuration contract](config.md) owns public behavior. ## Initial orientation 1. Inspect the working tree and preserve unrelated changes. 2. Use the Policy Reading Guide below to select applicable policies. 3. Read the contract and internal documents applicable to the task. 4. Inspect the relevant implementation and behavioral tests before changing them. ## Policy Reading Guide | Policy | Read before… | | --- | --- | | [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. | | [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. | | [Architecture](policy/architecture.md) | Planning or changing Go library code or its structure. | | [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. | | [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. | | [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. | | [Release](policy/release.md) | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. | - Read applicable policies before making decisions they govern; multiple policies may apply. - Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question. - Reuse policies already available in context; reread when changed or no longer available. - Expand reading when the task's scope expands. - When revising a policy itself, read that policy and any provisions elsewhere affected by the revision. ## Task-specific reading guide | Task | Read | | --- | --- | | Repository orientation or component responsibility | [Component overview](internal/overview.md) | | Input destinations | [Configuration contract](config.md#input-destinations), [ADR 0011](adr/0011-input-destinations.md), and the destination tests below | | Shared source-version checks | [Configuration contract](config.md#shared-source-version-checks), [ADR 0013](adr/0013-shared-source-version-checks.md), and the version/source-version tests below | | Documentation changes | The owning document | | Licensing, dependencies, attribution, or release-document changes | [Project grant](../COPYRIGHT) and [attribution](oss/attribution.md); release changes also follow the release procedure | | Architecture decisions or future work | [Future features](roadmap/future.md) and relevant ADRs listed below | | Code and test changes | The owning contract and tests from the map below | | Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) | | Release preparation | [Release procedure](release.md) | Accepted decisions: - [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md) - [Check source versions with one shared policy](adr/0013-shared-source-version-checks.md) - [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md) - [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md) - [Explicit configured secrets bootstrap](adr/0023-explicit-configured-secrets-bootstrap.md) - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md) - [Keep the public facade root-owned](adr/0006-public-facade.md) - [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md) - [Compare inspection views across application types](adr/0024-compare-inspection-views-across-application-types.md) - [Place inputs at literal application mapping paths](adr/0011-input-destinations.md) - [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md) - [Separate import selection controls](adr/0016-independent-import-controls.md) - [Define identity and merge rules for each collection](adr/0017-collection-sequence-policy.md) - [Apply CLI overrides after inheritance and decoding](adr/0018-cli-after-structural-resolution.md) - [Keep main-file discovery explicit and composable](adr/0019-explicit-configuration-discovery.md) - [Scope configuration controls to document roots](adr/0020-document-root-controls.md) - [Match registered records during resolution inspection](adr/0021-sequence-resolution-correspondence.md) - [Bind companion contexts after main selection](adr/0022-main-relative-context.md) For cross-cutting changes, follow every applicable row. Use current contracts and the component overview for ongoing work. Release-candidate, publication, and verification work follows the operational [release procedure](release.md). Its module-selected ReleaseKit `publish` invocation validates the committed candidate and publishes only the intended tag; those release checks remain distinct from the everyday development check. ## Baseline validation Install the Go version required by `go.mod` or a compatible newer toolchain. Acquire declared dependencies explicitly before entering an offline development or validation environment: ```sh go mod download ``` Run the everyday check with Bash 3.2 or newer and Git: ```sh ./scripts/check.sh ``` [The script](../scripts/check.sh) runs from the repository root regardless of the invocation directory. It checks Go formatting without rewriting files, checks staged/unstaged and untracked whitespace, then runs `go test ./...`, `go vet ./...`, and `go build ./...`, stopping on the first failure. It uses the installed Go toolchain by default, honors an explicit `GOTOOLCHAIN`, and disables dependency downloads. Acquire dependencies and any selected toolchain beforehand. Format reported Go files with `gofmt -w `. The default suite includes executable examples, maintained consumer fixtures, and the dependency/public boundary checks. It must stay deterministic and runnable without network access or credentials. Still inspect new/untracked content and review paths, examples, ownership, and current-versus-planned claims; automated checks do not replace content review. Use focused checks while iterating, with validation proportionate to the change under the testing policy. Documentation-only work normally needs review of affected links and whitespace; behavior-bearing examples and commands also need execution. Automated Markdown link checking runs against the committed candidate through ReleaseKit, not during ordinary Go tests or the everyday checker. See the [release procedure](release.md#4-publish-the-committed-candidate) for the selected checks and optional diagnostic command. Use `go test -race ./...` for ownership or concurrency changes. The [release procedure](release.md#4-publish-the-committed-candidate) performs its selected validation through one `publish` invocation. The everyday checker remains a development gate and is not a separate release prerequisite. CI never gates a release. ## Task-to-test map Commands run from the repository root after dependency acquisition. These are starting points for focused iteration; run the everyday check before handing off code changes. Use the component overview to find the corresponding implementation. | Task | Behavioral test owners | Focused command | | --- | --- | --- | | YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` | | File/reader access, imports, globs, containment | [Import internals](internal/imports.md), [source acquisition](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [import traversal](../internal/engine/imports_test.go), [import evidence](../internal/engine/import_evidence_test.go), [relative destinations](../internal/engine/destination_import_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` | | Explicit main-file discovery and absent-input loading | [Candidate selection](../internal/engine/discovery_test.go), [load integration](../internal/engine/discovery_load_test.go), [public facade](../facade_discovery_test.go), and maintained [catalog](../examples/consumers/sequence_catalog_test.go) and [preset](../examples/consumers/discovery_test.go) examples | `go test ./internal/engine -run 'Discovery\|Search'`, `go test . -run 'Search'`, and `go test ./examples/consumers -run 'WorkingDirectoryPreset\|SequenceCatalog'` | | Import defaults, empty-selection evidence, and dependency-ready ordering | [Defaults and facade evidence](../facade_import_defaults_test.go), [engine import evidence](../internal/engine/import_evidence_test.go), [scheduler](../internal/engine/dependency_order_test.go), [scheduling integrations](../internal/engine/imports_test.go) | `go test ./internal/engine -run 'Import\|ScheduleDependencies\|Inheritance'`, `go test . -run 'ImportDefaults\|FacadeImport'`, and `go test ./examples/consumers` | | Native filesystem and mapping sources | [Native acquisition](../internal/engine/native_filesystem_test.go), [filesystem facade](../facade_filesystem_test.go), [mapping facade](../facade_mapping_test.go) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` | | Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` | | Sequence identity, declarations, and operations | [Identity](../internal/engine/sequence_identity_test.go), [registrations](../internal/engine/sequence_registration_test.go), [declarations](../internal/engine/sequence_declaration_test.go), [combination](../internal/engine/sequence_combine_test.go), [final facade validation](../facade_final_sequence_identity_test.go), and [consumer catalog](../examples/consumers/sequence_catalog_test.go) | `go test ./internal/engine -run 'Sequence\|Collection'`, `go test . -run 'SequenceIdentity\|SequenceRegistration'`, and `go test ./examples/consumers` | | Sibling inheritance, provenance, history, sensitivity | [Implementation flow](internal/overview.md#implementation-flow), [expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` | | Layered loading and source equivalence | [Grouped lifecycle](../internal/engine/load_request_test.go), [layered facade](../facade_layered_test.go), [equivalence](../facade_equivalence_test.go) | `go test ./internal/engine -run '^TestGrouped'`, `go test . -run '^TestFacadeLayered'`, and `go test . -run '^TestEquivalentSourceForms'` | | Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'`, `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'`, and `go test ./examples/consumers` | | Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` | | Schema, defaults, projection, cloning | [Implementation flow](internal/overview.md#implementation-flow), [schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection and typed cloning](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` | | Current values and focused inspection | [Value tests](../facade_result_value_test.go), [view tests](../facade_inspection_view_test.go), [comparison tests](../facade_inspection_diff_test.go), and [history integration](../facade_inspection_history_test.go) | `go test . -run 'TestResultValue\|TestInspectionView'` and `go test ./internal/engine -run 'TestResultValue\|Diff\|History'` | | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` | | Resolution sequence matching and inspection | [Correspondence](../internal/engine/resolution_correspondence_test.go), [auditing and history](../internal/engine/resolution_compare_test.go), [public integration](../facade_resolution_sequences_test.go) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` | | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` | | Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` | | Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [directory bootstrap](../internal/engine/secrets_test.go), [configured preparation](../internal/engine/secrets_from_config_test.go), [public handoff](../facade_secrets_handoff_test.go), [consumer example](../examples/consumers/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'`, `go test . -run 'Secrets\|Bootstrap'`, and `go test ./examples/consumers -run 'ConfiguredSecrets'` | | Effective configuration diff | [Engine comparison and masking tests](../internal/engine/diff_test.go), [engine operation tests](../internal/engine/diff_operation_test.go), [root facade tests](../facade_diff_test.go), and [consumer examples](../examples/consumers/diff_test.go) | `go test ./internal/engine -run 'Diff\|Explain\|History\|Secret\|Independent'`, `go test . -run 'Diff\|FacadeInspection\|PublicFacadeBoundary\|DependencyImportBoundary'`, `go test ./examples/consumers`, and `go test . -run '^ExampleDiff$'` | | Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native, layered, and ordinary relative-import examples](../examples/consumers/layered_test.go), [mounted collection examples](../examples/consumers/destinations_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` | | Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` | | Identified-sequence scaling evidence | [Mixed-upsert benchmark](../internal/engine/sequence_combine_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem` | | Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` | | Dependency and public API isolation | [Import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestDependencyImportBoundary\|TestPublicFacadeBoundary'` | | Development check behavior | [Development checker test](../development_check_test.go) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` | ## Fuzz validation Run the bounded fuzz targets independently from the repository root. These exact commands keep each campaign short and constrain concurrent workers: ```sh go test ./internal/engine -run='^$' -fuzz='^FuzzParsePath$' -fuzztime=30s -parallel=2 go test ./internal/yaml -run='^$' -fuzz='^FuzzParseDocument$' -fuzztime=30s -parallel=2 go test ./internal/engine -run='^$' -fuzz='^FuzzCompositionAndOverlay$' -fuzztime=30s -parallel=2 ```