Retire completed roadmaps and preserve release gates
This commit is contained in:
@@ -33,9 +33,7 @@ func ReadConfig(path string) (Config, error) {
|
|||||||
The [configuration contract](docs/config.md) describes implemented behavior. The
|
The [configuration contract](docs/config.md) describes implemented behavior. The
|
||||||
[consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
|
[consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
|
||||||
Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
|
Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
|
||||||
The [initial target record](docs/roadmap/initial.md) links implemented feature owners
|
The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions. See the
|
||||||
and preserves deliberately deferred scope. The [implementation plan](docs/roadmap/implementation.md)
|
|
||||||
records completion evidence until release-candidate preparation retires it. See the
|
|
||||||
[development guide](docs/development.md) for repository orientation and the
|
[development guide](docs/development.md) for repository orientation and the
|
||||||
[release procedure](docs/release.md) for maintainer-only candidate and publication
|
[release procedure](docs/release.md) for maintainer-only candidate and publication
|
||||||
steps.
|
steps.
|
||||||
|
|||||||
@@ -18,7 +18,7 @@ public behavior.
|
|||||||
| --- | --- |
|
| --- | --- |
|
||||||
| Repository orientation or component responsibility | [Architecture policy](policy/architecture.md) and [component overview](internal/overview.md) |
|
| Repository orientation or component responsibility | [Architecture policy](policy/architecture.md) and [component overview](internal/overview.md) |
|
||||||
| Documentation changes | [Documentation policy](policy/documentation.md) and the owning document |
|
| Documentation changes | [Documentation policy](policy/documentation.md) and the owning document |
|
||||||
| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [initial target record](roadmap/initial.md), and relevant ADRs listed below |
|
| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [deferred scope](roadmap/deferred.md), and relevant ADRs listed below |
|
||||||
| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and the owning contract and tests from the map below |
|
| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and the owning contract and tests from the map below |
|
||||||
| Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
|
| Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
|
||||||
| Release preparation | [Release policy](policy/release.md), [release procedure](release.md), and [release-readiness evidence](roadmap/release-readiness.md) |
|
| Release preparation | [Release policy](policy/release.md), [release procedure](release.md), and [release-readiness evidence](roadmap/release-readiness.md) |
|
||||||
@@ -31,9 +31,16 @@ Accepted decisions:
|
|||||||
- [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
|
- [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
|
||||||
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
|
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
|
||||||
|
|
||||||
For cross-cutting changes, follow every applicable row. The
|
For cross-cutting changes, follow every applicable row. Completed implementation
|
||||||
[implementation plan](roadmap/implementation.md) owns the ordered stages and their
|
and remediation plans are preserved in Git history at `cb5b435`; use current
|
||||||
acceptance checks and recorded implementation evidence.
|
contracts and the component overview for ongoing work. For example:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
git show cb5b435:docs/roadmap/remediation.md
|
||||||
|
```
|
||||||
|
|
||||||
|
Outstanding release work and preparation evidence remain in the
|
||||||
|
[release-readiness record](roadmap/release-readiness.md).
|
||||||
|
|
||||||
## Baseline validation
|
## Baseline validation
|
||||||
|
|
||||||
@@ -81,14 +88,14 @@ code changes. Use the component overview to find the corresponding implementatio
|
|||||||
| Task | Behavioral test owners | Focused command |
|
| Task | Behavioral test owners | Focused command |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../parse_test.go) | `go test ./internal/yaml` and `go test . -run '^TestParseSource'` |
|
| YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../parse_test.go) | `go test ./internal/yaml` and `go test . -run '^TestParseSource'` |
|
||||||
| File/reader access, imports, globs, containment | [Sources](../source_test.go), [FIFO](../source_fifo_test.go), [imports](../imports_test.go), [globs](../glob_test.go) | `go test . -run 'Source|Import|Glob|Filesystem|Nonregular|RegularFile'` |
|
| File/reader access, imports, globs, containment | [Sources](../source_test.go), [FIFO](../source_fifo_test.go), [imports](../imports_test.go), [globs](../glob_test.go) | `go test . -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
|
||||||
| Composition, profiles, CLI precedence | [Composition](../compose_test.go), [overlay](../overlay_test.go), [profiles](../profile_test.go), [overrides](../override_test.go) | `go test . -run 'Compose|Overlay|Profile|Override'` |
|
| Composition, profiles, CLI precedence | [Composition](../compose_test.go), [overlay](../overlay_test.go), [profiles](../profile_test.go), [overrides](../override_test.go) | `go test . -run 'Compose\|Overlay\|Profile\|Override'` |
|
||||||
| Schema, defaults, projection, cloning | [Schema](../schema_test.go), [decoding](../decode_test.go), [projection](../projection_test.go) | `go test . -run 'Schema|Decode|Projection|Clone|Inline|CompareDocument'` |
|
| Schema, defaults, projection, cloning | [Schema](../schema_test.go), [decoding](../decode_test.go), [projection](../projection_test.go) | `go test . -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
|
||||||
| Lifecycle, resolution, validation, callback ownership | [Loading](../load_test.go), [resolution](../resolution_test.go), [validation](../validation_test.go), [ownership](../callback_ownership_test.go), [independence](../independence_test.go) | `go test . -run 'Load|Resolution|Validation|Validator|Hook|Callback|Parallel'` |
|
| Lifecycle, resolution, validation, callback ownership | [Loading](../load_test.go), [resolution](../resolution_test.go), [validation](../validation_test.go), [ownership](../callback_ownership_test.go), [independence](../independence_test.go) | `go test . -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
|
||||||
| Paths, metadata, provenance | [Paths](../path_test.go), [metadata](../metadata_test.go), [provenance](../provenance_test.go) | `go test . -run 'Path|Metadata|Provenance|Queries'` |
|
| Paths, metadata, provenance | [Paths](../path_test.go), [metadata](../metadata_test.go), [provenance](../provenance_test.go) | `go test . -run 'Path\|Metadata\|Provenance\|Queries'` |
|
||||||
| Secrets, bootstrap, redaction, explanation | [References](../secret_reference_test.go), [bootstrap](../secrets_test.go), [rendering](../render_test.go), [explanation](../explain_test.go) | `go test . -run 'Secret|Bootstrap|Effective|Explain|Explanation|History|Sensitivity'` |
|
| Secrets, bootstrap, redaction, explanation | [References](../secret_reference_test.go), [bootstrap](../secrets_test.go), [rendering](../render_test.go), [explanation](../explain_test.go) | `go test . -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
|
||||||
| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
|
| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
|
||||||
| Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go) | `go test . -run '^(TestLocalDocumentationLinks|TestDependencyImportBoundary)$'` |
|
| Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go) | `go test . -run '^(TestLocalDocumentationLinks\|TestDependencyImportBoundary)$'` |
|
||||||
| Check-command behavior | [Shell regression](../release_check_test.go) | `go test . -run '^TestCheckScripts'` |
|
| Check-command behavior | [Shell regression](../release_check_test.go) | `go test . -run '^TestCheckScripts'` |
|
||||||
|
|
||||||
## Fuzz validation
|
## Fuzz validation
|
||||||
|
|||||||
@@ -59,7 +59,8 @@ representations private. The implemented components and their owners are:
|
|||||||
`internal/yaml/write.go`;
|
`internal/yaml/write.go`;
|
||||||
- a separate maintained `examples/consumers` package with four sanitized consumer
|
- a separate maintained `examples/consumers` package with four sanitized consumer
|
||||||
shapes, fixtures, domain validators, and runtime-boundary functions; and
|
shapes, fixtures, domain validators, and runtime-boundary functions; and
|
||||||
- a fail-fast source-candidate checker in `scripts/release-check.sh`, with local
|
- an everyday single-toolchain check in `scripts/check.sh` and a stricter
|
||||||
|
source-candidate checker in `scripts/release-check.sh`, with local
|
||||||
documentation-link and public import-boundary gates owned by root-package tests.
|
documentation-link and public import-boundary gates owned by root-package tests.
|
||||||
|
|
||||||
Dependency direction remains inward: the public lifecycle coordinates private
|
Dependency direction remains inward: the public lifecycle coordinates private
|
||||||
@@ -82,7 +83,7 @@ implementation:
|
|||||||
- [Extraction inventory](extraction.md)
|
- [Extraction inventory](extraction.md)
|
||||||
|
|
||||||
The [architecture policy](../policy/architecture.md) owns binding boundaries and
|
The [architecture policy](../policy/architecture.md) owns binding boundaries and
|
||||||
invariants. The [initial target record](../roadmap/initial.md) links current feature
|
invariants. The [deferred scope](../roadmap/deferred.md) records deliberate
|
||||||
owners and preserves deferred scope; it is not an implementation inventory. See the
|
exclusions. See the
|
||||||
[development guide](../development.md) for contributor orientation and validation
|
[development guide](../development.md) for contributor orientation and validation
|
||||||
and the [release procedure](../release.md) for source-candidate gates.
|
and the [release procedure](../release.md) for source-candidate gates.
|
||||||
|
|||||||
@@ -10,7 +10,7 @@ ConfigKit is an opinionated Go library for consistent YAML configuration loading
|
|||||||
and resolution across consuming applications. This policy governs contributions.
|
and resolution across consuming applications. This policy governs contributions.
|
||||||
The [component overview](../internal/overview.md) owns implementation inventory, the
|
The [component overview](../internal/overview.md) owns implementation inventory, the
|
||||||
[configuration contract](../config.md) owns implemented behavior, and the
|
[configuration contract](../config.md) owns implemented behavior, and the
|
||||||
[initial target record](../roadmap/initial.md) preserves deferred scope.
|
[deferred scope](../roadmap/deferred.md) preserves deferred scope.
|
||||||
|
|
||||||
## Success criteria
|
## Success criteria
|
||||||
|
|
||||||
@@ -136,7 +136,7 @@ for safe messages supplied by their hooks.
|
|||||||
Do not introduce automatic directory discovery, network providers, arbitrary
|
Do not introduce automatic directory discovery, network providers, arbitrary
|
||||||
merge strategies, additional configuration languages, or application runtime
|
merge strategies, additional configuration languages, or application runtime
|
||||||
management without concrete consumer evidence and an explicit design decision.
|
management without concrete consumer evidence and an explicit design decision.
|
||||||
The [initial target record](../roadmap/initial.md#explicit-non-goals-and-deferred-scope)
|
The [deferred scope](../roadmap/deferred.md#explicit-non-goals-and-deferred-scope)
|
||||||
owns the deferred-feature inventory. Significant boundary
|
owns the deferred-feature inventory. Significant boundary
|
||||||
changes require an ADR and corresponding policy/contract updates; implementation
|
changes require an ADR and corresponding policy/contract updates; implementation
|
||||||
convenience alone is not a reason to broaden the public API.
|
convenience alone is not a reason to broaden the public API.
|
||||||
|
|||||||
@@ -28,8 +28,8 @@ semantics, defaults, paths, diagnostics, or compatibility guarantees.
|
|||||||
implementation; execution status belongs in roadmaps.
|
implementation; execution status belongs in roadmaps.
|
||||||
- Roadmaps own unimplemented targets, deferred work, and execution status.
|
- Roadmaps own unimplemented targets, deferred work, and execution status.
|
||||||
|
|
||||||
The initial target and implementation plan have separate owners. Do not put
|
Future implementation plans own their task order, acceptance gates, and progress;
|
||||||
staged steps or progress in `docs/roadmap/initial.md`. `docs/roadmap/implementation.md` owns those details.
|
`docs/roadmap/deferred.md` owns deliberate exclusions, not execution instructions.
|
||||||
As behavior lands, move its normative definition into the current contract and
|
As behavior lands, move its normative definition into the current contract and
|
||||||
replace the roadmap definition with a link. Retire completed roadmap material
|
replace the roadmap definition with a link. Retire completed roadmap material
|
||||||
as part of release preparation; ADRs preserve significant decision history.
|
as part of release preparation; ADRs preserve significant decision history.
|
||||||
@@ -56,7 +56,7 @@ handling, not secret values.
|
|||||||
|
|
||||||
| Topic | Owner | Boundary |
|
| Topic | Owner | Boundary |
|
||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example once available |
|
| Product orientation | `README.md` | Current status, purpose, navigation, and a minimal working example |
|
||||||
| Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands |
|
| Contributor entry point | `docs/development.md` | Reading guide and actual baseline validation commands |
|
||||||
| Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
|
| Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
|
||||||
| Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle |
|
| Documentation rules | `docs/policy/documentation.md` | Ownership and document lifecycle |
|
||||||
@@ -64,13 +64,13 @@ handling, not secret values.
|
|||||||
| Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
|
| Release rules | `docs/policy/release.md` | Compatibility, integrity, gates, immutability, and exceptions |
|
||||||
| Release procedure | `docs/release.md` | Exact maintainer commands, prerequisites, supported targets, and verification |
|
| Release procedure | `docs/release.md` | Exact maintainer commands, prerequisites, supported targets, and verification |
|
||||||
| Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
|
| Exported Go API | Go documentation beside declarations | Symbol contracts, errors, ownership, and lifecycle API behavior |
|
||||||
| YAML and resolution semantics | `docs/config.md`, as behavior lands | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
|
| YAML and resolution semantics | `docs/config.md` | Syntax, composition, precedence, conversion, secret references/bootstrap, and explanation semantics; Go reference docs link here for shared rules |
|
||||||
| Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
|
| Consumer walkthroughs | `docs/consumers/`, when useful | Task-oriented usage and consumer responsibilities, not duplicate API reference |
|
||||||
| Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
|
| Component inventory | `docs/internal/overview.md` | Implemented components and links to their owners |
|
||||||
| Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
|
| Component mechanics | Other `docs/internal/` files, when needed | Detailed implementation behavior and change recipes |
|
||||||
| Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
|
| Architectural decisions | `docs/adr/` | Context, decisions, alternatives, consequences, and supersession history |
|
||||||
| Initial target record | `docs/roadmap/initial.md` | Implemented-feature owner links and deferred feature scope until roadmap retirement |
|
| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and the conditions for reconsidering them |
|
||||||
| Implementation plan | `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
|
| Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, task order, acceptance gates, and progress; completed plans retire to Git history |
|
||||||
| Release readiness evidence | `docs/roadmap/release-readiness.md` | Closed preparation gaps and outstanding candidate/publication evidence until roadmap retirement |
|
| Release readiness evidence | `docs/roadmap/release-readiness.md` | Closed preparation gaps and outstanding candidate/publication evidence until roadmap retirement |
|
||||||
| Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
|
| Historical release notes | `docs/releases/` | Version-specific historical summaries required by release policy |
|
||||||
| Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |
|
| Complete examples | `examples/` and executable Go examples | Maintained artifacts; prose links instead of duplicating full examples |
|
||||||
|
|||||||
28
docs/roadmap/deferred.md
Normal file
28
docs/roadmap/deferred.md
Normal file
@@ -0,0 +1,28 @@
|
|||||||
|
# Deferred Scope
|
||||||
|
|
||||||
|
This document owns intentionally excluded features, not a committed delivery plan.
|
||||||
|
The [architecture policy](../policy/architecture.md) governs changes to these
|
||||||
|
boundaries. Implemented behavior belongs in the [configuration contract](../config.md)
|
||||||
|
and consumer adoption in the [consumer guide](../consumers/README.md).
|
||||||
|
|
||||||
|
## Explicit non-goals and deferred scope
|
||||||
|
|
||||||
|
General environment-variable configuration overlays are not supported. Typed secret
|
||||||
|
references and explicit directory bootstrap are the environment convention. Literal
|
||||||
|
credential configuration and implicit secret-directory discovery are unsupported.
|
||||||
|
|
||||||
|
The initial release deliberately excludes:
|
||||||
|
|
||||||
|
- automatic `conf.d` discovery;
|
||||||
|
- remote imports, arbitrary providers, and additional configuration formats;
|
||||||
|
- custom merge strategies, sequence merging, reset operators, and profile inheritance;
|
||||||
|
- parser-specific or custom structural-decoding extension APIs;
|
||||||
|
- generic dynamic-subtree conversion and module-registry APIs;
|
||||||
|
- automatic schema migrations;
|
||||||
|
- hot reload, runtime resource replacement, and remote resource validation;
|
||||||
|
- a bundled CLI framework or application commands; and
|
||||||
|
- configuration diffs and fingerprints.
|
||||||
|
|
||||||
|
Applications may build their own validate, effective-value, source, bootstrap, and
|
||||||
|
explanation commands around the library. Broadening these boundaries requires
|
||||||
|
concrete consumer evidence, compatibility review, and an explicit design change.
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -1,83 +0,0 @@
|
|||||||
# ConfigKit Initial Target Record
|
|
||||||
|
|
||||||
## Status and ownership
|
|
||||||
|
|
||||||
The initial feature target is implemented. This document now records the intended
|
|
||||||
outcome, source foundations, and deliberately deferred scope without duplicating the
|
|
||||||
current configuration contract or Go API reference. Ordered implementation history
|
|
||||||
and acceptance evidence remain in the [implementation plan](implementation.md) until
|
|
||||||
the maintainer retires completed roadmaps while preparing a release candidate.
|
|
||||||
|
|
||||||
The [architecture policy](../policy/architecture.md) owns responsibilities,
|
|
||||||
dependency direction, confidentiality, and the two success criteria. The
|
|
||||||
[configuration contract](../config.md) and Go declarations own implemented behavior.
|
|
||||||
The [consumer adoption guide](../consumers/README.md) owns consumer fit and migration
|
|
||||||
guidance. Accepted rationale remains in the [ADRs](../development.md#task-specific-reading-guide).
|
|
||||||
|
|
||||||
## Initial outcome
|
|
||||||
|
|
||||||
ConfigKit is one opinionated Go library for strict YAML configuration loading. It
|
|
||||||
removes source handling, parsing, explicit import/profile traversal, composition,
|
|
||||||
precedence, presence tracking, provenance, secret lookup/bootstrap, diagnostics, and
|
|
||||||
safe inspection plumbing from applications. Applications retain their types,
|
|
||||||
defaults, schema-version policy, recorded normalization, semantic validation, CLI
|
|
||||||
parsing, remote acquisition, domain algorithms, resource checks, and runtime setup.
|
|
||||||
|
|
||||||
The maintained Narratio-, Notarius-, WeatherReporter-, and Seriatim-shaped examples
|
|
||||||
demonstrate both architecture success criteria: simple consumers avoid optional
|
|
||||||
composition machinery, complex consumers use the same conventions, and domain logic
|
|
||||||
remains recognizable application code. These examples are migration evidence, not a
|
|
||||||
claim that any sibling application has migrated.
|
|
||||||
|
|
||||||
## Implementation foundations
|
|
||||||
|
|
||||||
The implementation was generalized from maintainer-authorized application code and
|
|
||||||
tests at fixed clean revisions. The [extraction inventory](../internal/extraction.md)
|
|
||||||
records exact revisions, symbols, adapted cases, intentional semantic differences,
|
|
||||||
and the boundary that keeps sibling checkouts out of builds and tests. Links from
|
|
||||||
that inventory or historical implementation evidence to sibling source are optional
|
|
||||||
in isolated clones; immutable revision references remain authoritative evidence.
|
|
||||||
|
|
||||||
The module uses `go.yaml.in/yaml/v4` only behind `internal/yaml`. ConfigKit owns the
|
|
||||||
document model, field binding, scalar grammar, errors, limits, and output behavior.
|
|
||||||
No upstream type, option, plugin, error chain, hidden parser value, or generic
|
|
||||||
constraint crosses the public API. The package-level import-boundary test enforces
|
|
||||||
this isolation for production, tests, and maintained examples.
|
|
||||||
|
|
||||||
## Current feature owners
|
|
||||||
|
|
||||||
| Initial feature area | Current owner |
|
|
||||||
| --- | --- |
|
|
||||||
| Sources, lifecycle, limits, YAML/scalars, decoding, and ownership | [Configuration contract](../config.md) and Go reference comments |
|
|
||||||
| Paths, presence, origins, sources, and definition history | [Layered metadata](../config.md#layered-metadata), [`path.go`](../../path.go), and [`metadata.go`](../../metadata.go) |
|
|
||||||
| Strict composition, imports, globs, source identity, and profiles | [Strict composition](../config.md#strict-document-composition), [explicit imports](../config.md#explicit-imports), and [selected profiles](../config.md#selected-profiles) |
|
|
||||||
| Static defaults, null, types, projection, and custom text scalars | [Defaults and typed decoding](../config.md#defaults-and-typed-decoding), [schema binding](../config.md#application-schema-binding), and [typed projection](../config.md#typed-projection-and-ownership) |
|
|
||||||
| Schema versions, recorded resolution, and semantic validation | [Version contract](../config.md#application-schema-versions), [resolution](../config.md#recorded-application-resolution), and [validation](../config.md#semantic-validation) |
|
|
||||||
| Secret classification, typed references, and directory bootstrap | [Redaction](../config.md#secret-classification-and-effective-rendering), [references](../config.md#typed-secret-references), and [bootstrap](../config.md#explicit-secrets-directory-bootstrap) |
|
|
||||||
| Explicit CLI overrides and complete precedence | [CLI override contract](../config.md#explicit-cli-overrides) |
|
|
||||||
| Effective rendering and safe historical explanation | [Effective rendering](../config.md#secret-classification-and-effective-rendering) and [historical explanation](../config.md#historical-value-explanation) |
|
|
||||||
| Canonical module options and downstream adoption | [Module options](../config.md#canonical-module-options) and [consumer guide](../consumers/README.md) |
|
|
||||||
| Diagnostics and structured errors | [`records.go`](../../records.go), [`diagnostic.go`](../../diagnostic.go), and relevant configuration-contract sections |
|
|
||||||
| Internal components and dependency placement | [Component overview](../internal/overview.md) and [architecture policy](../policy/architecture.md) |
|
|
||||||
|
|
||||||
## Explicit non-goals and deferred scope
|
|
||||||
|
|
||||||
General environment-variable configuration overlays are not supported. Typed secret
|
|
||||||
references and explicit directory bootstrap are the environment convention. Literal
|
|
||||||
credential configuration and implicit secret-directory discovery are unsupported.
|
|
||||||
|
|
||||||
The initial release deliberately excludes:
|
|
||||||
|
|
||||||
- automatic `conf.d` discovery;
|
|
||||||
- remote imports, arbitrary providers, and additional configuration formats;
|
|
||||||
- custom merge strategies, sequence merging, reset operators, and profile inheritance;
|
|
||||||
- parser-specific or custom structural-decoding extension APIs;
|
|
||||||
- generic dynamic-subtree conversion and module-registry APIs;
|
|
||||||
- automatic schema migrations;
|
|
||||||
- hot reload, runtime resource replacement, and remote resource validation;
|
|
||||||
- a bundled CLI framework or application commands; and
|
|
||||||
- configuration diffs and fingerprints.
|
|
||||||
|
|
||||||
Applications may build their own validate, effective-value, source, bootstrap, and
|
|
||||||
explanation commands around the library. Broadening these boundaries requires
|
|
||||||
concrete consumer evidence, compatibility review, and an explicit design change.
|
|
||||||
@@ -6,9 +6,10 @@ ConfigKit's implementation is prepared for release-candidate validation, but no
|
|||||||
release candidate has been selected or publication authorized. The maintainer
|
release candidate has been selected or publication authorized. The maintainer
|
||||||
preparing the first release owns the remaining gates under the
|
preparing the first release owns the remaining gates under the
|
||||||
[temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
|
[temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
|
||||||
This evidence record remains until candidate preparation retires completed roadmap
|
Completed implementation, remediation, and initial-target records have retired to
|
||||||
material in favor of the operational [release procedure](../release.md) and normal
|
Git history at `cb5b435`. [Deferred scope](deferred.md) remains separate. This
|
||||||
release notes.
|
record retains preparation evidence and unresolved release gates until their
|
||||||
|
closure is recorded under the operational [release procedure](../release.md).
|
||||||
|
|
||||||
## Preparation evidence
|
## Preparation evidence
|
||||||
|
|
||||||
@@ -17,6 +18,8 @@ release notes.
|
|||||||
| Module and support matrix | Closed: the runbook records module `gitea.maximumdirect.net/eric/ConfigKit`, minimum Go 1.25 with a patched 1.25 plus newer supported toolchain, and Linux/macOS on amd64/arm64. |
|
| Module and support matrix | Closed: the runbook records module `gitea.maximumdirect.net/eric/ConfigKit`, minimum Go 1.25 with a patched 1.25 plus newer supported toolchain, and Linux/macOS on amd64/arm64. |
|
||||||
| Maintainer release procedure | Closed: `docs/release.md` owns access prerequisites, candidate recording, complete validation, exact remote/commit/tag guards, source-only publication, consumer retrieval, and correction. |
|
| Maintainer release procedure | Closed: `docs/release.md` owns access prerequisites, candidate recording, complete validation, exact remote/commit/tag guards, source-only publication, consumer retrieval, and correction. |
|
||||||
| Automated source checker | Closed for current-source preparation: `scripts/release-check.sh` passed on 2026-09-06 with Go 1.25.5 and Go 1.26.7 on linux/amd64. It performs disposable-copy module hygiene, cached/offline tests, race, vet, native and four-target cross-builds, formatting/whitespace, examples, import isolation, and local-link gates. The exact candidate must rerun it. |
|
| Automated source checker | Closed for current-source preparation: `scripts/release-check.sh` passed on 2026-09-06 with Go 1.25.5 and Go 1.26.7 on linux/amd64. It performs disposable-copy module hygiene, cached/offline tests, race, vet, native and four-target cross-builds, formatting/whitespace, examples, import isolation, and local-link gates. The exact candidate must rerun it. |
|
||||||
|
| Maintainability remediation | Closed: all nine stages completed in `cb5b435`; the full checker passed on 2026-09-07 with Go 1.25.5 and Go 1.26.7 on Linux/amd64. The recorded audit found all 186 exported declarations unchanged, no dependency changes, and passing native FIFO/symlink/permission tests. |
|
||||||
|
| Roadmap retirement | Closed for current-source preparation: completed implementation, remediation, and initial-target records were removed, navigation repaired, and deferred scope retained separately. Maintainer rechecks for any newly completed roadmap material when selecting the candidate. |
|
||||||
| Consumer verification procedure | Closed as procedure: the runbook retrieves an exact published version into a clean temporary module with no local replacement and tests/builds it. Actual retrieval remains a post-publication gate. |
|
| Consumer verification procedure | Closed as procedure: the runbook retrieves an exact published version into a clean temporary module with no local replacement and tests/builds it. Actual retrieval remains a post-publication gate. |
|
||||||
| Secret/precedence/explanation evidence | Closed locally: current contracts and deterministic tests cover bootstrap skip/partial failure, credential isolation, defaults/base/profile/CLI precedence, historical redaction, and maintained consumer startup examples. |
|
| Secret/precedence/explanation evidence | Closed locally: current contracts and deterministic tests cover bootstrap skip/partial failure, credential isolation, defaults/base/profile/CLI precedence, historical redaction, and maintained consumer startup examples. |
|
||||||
| Parser dependency reassessment | Closed for preparation: on 2026-09-06, `go list -m -versions go.yaml.in/yaml/v4` and `go list -m -json go.yaml.in/yaml/v4@latest` both showed `v4.0.0-rc.6` as the newest available release. The explicit pin is retained; a candidate compatibility review must reassess and record it again. |
|
| Parser dependency reassessment | Closed for preparation: on 2026-09-06, `go list -m -versions go.yaml.in/yaml/v4` and `go list -m -json go.yaml.in/yaml/v4@latest` both showed `v4.0.0-rc.6` as the newest available release. The explicit pin is retained; a candidate compatibility review must reassess and record it again. |
|
||||||
@@ -28,7 +31,6 @@ release notes.
|
|||||||
| Exact candidate and release note | Maintainer selects an unused stable version, writes `docs/releases/<version>.md`, commits all release changes, runs the checker against that exact clean commit, pushes it to `origin/main`, and records the commit. |
|
| Exact candidate and release note | Maintainer selects an unused stable version, writes `docs/releases/<version>.md`, commits all release changes, runs the checker against that exact clean commit, pushes it to `origin/main`, and records the commit. |
|
||||||
| Native platform execution | Maintainer records applicable checker, race, symlink, and permission-fixture results on native Linux and macOS. Current local evidence is Linux/amd64 only; cross-builds do not close macOS execution. |
|
| Native platform execution | Maintainer records applicable checker, race, symlink, and permission-fixture results on native Linux and macOS. Current local evidence is Linux/amd64 only; cross-builds do not close macOS execution. |
|
||||||
| Compatibility, migration, and content review | Maintainer records public API/configuration/diagnostic review, downstream migration impact, release-note approval, and inspection for credentials, private data, generated output, unintended files, and unrelated changes. |
|
| Compatibility, migration, and content review | Maintainer records public API/configuration/diagnostic review, downstream migration impact, release-note approval, and inspection for credentials, private data, generated output, unintended files, and unrelated changes. |
|
||||||
| Roadmap retirement | Maintainer removes obsolete completed files under `docs/roadmap/`, repairs inbound links, and reruns the checker as part of the candidate. This record and the implementation plan intentionally remain while no candidate exists. |
|
|
||||||
| Remote publication guards | Maintainer fetches authoritative `origin/main` and tags immediately before publication and proves branch, clean worktree/index, candidate commit, remote commit, release note, approvals, and unused version all agree. |
|
| Remote publication guards | Maintainer fetches authoritative `origin/main` and tags immediately before publication and proves branch, clean worktree/index, candidate commit, remote commit, release note, approvals, and unused version all agree. |
|
||||||
| Tag and retrieval verification | After authorization, maintainer pushes only the exact immutable source tag, verifies its peeled remote commit, and retrieves/tests/builds the exact version in a clean consumer module without `replace`. |
|
| Tag and retrieval verification | After authorization, maintainer pushes only the exact immutable source tag, verifies its peeled remote commit, and retrieves/tests/builds the exact version in a clean consumer module without `replace`. |
|
||||||
|
|
||||||
|
|||||||
@@ -1,458 +0,0 @@
|
|||||||
# Pre-release Maintainability Remediation
|
|
||||||
|
|
||||||
## Status and scope
|
|
||||||
|
|
||||||
Status: complete; all nine stages are implemented and validated below.
|
|
||||||
Release-candidate selection and publication remain separate maintainer work.
|
|
||||||
Audit baseline: `9b147bfd96aec25e0125dcae66e136e56dc7a670`.
|
|
||||||
|
|
||||||
This roadmap owns the agreed maintainability cleanup before v0.1.0. It replaces
|
|
||||||
the completed implementation-defect remediation record, whose findings, fixes,
|
|
||||||
and validation evidence remain available in Git history. It does not reopen
|
|
||||||
those defects or replace the original [implementation plan](implementation.md).
|
|
||||||
|
|
||||||
The audit found worthwhile consolidation and ownership improvements, rather than
|
|
||||||
a need to redesign ConfigKit. The offline default suite and vet passed at the
|
|
||||||
audit baseline. That evidence is not validation of future changes or a release
|
|
||||||
candidate.
|
|
||||||
|
|
||||||
Read the [development guide](../development.md),
|
|
||||||
[architecture policy](../policy/architecture.md),
|
|
||||||
[testing policy](../policy/testing.md), and
|
|
||||||
[documentation policy](../policy/documentation.md) before implementation.
|
|
||||||
The [configuration contract](../config.md) owns current semantics; the
|
|
||||||
[component overview](../internal/overview.md) owns implementation inventory.
|
|
||||||
Release preparation remains governed by the [release policy](../policy/release.md)
|
|
||||||
and [maintainer procedure](../release.md).
|
|
||||||
|
|
||||||
## Execution rules and invariants
|
|
||||||
|
|
||||||
Implement the numbered stages in order. Each stage is one reviewable unit of
|
|
||||||
work: inspect its current owners and tests, make the change, validate it, update
|
|
||||||
its status and evidence here, and commit the nonempty unit with a short plain
|
|
||||||
English message. Do not create empty commits. Record any discovered behavioral
|
|
||||||
defect separately with a reproduction rather than silently changing semantics
|
|
||||||
under a refactoring stage.
|
|
||||||
|
|
||||||
Keep the root public package and the existing `internal/document` and
|
|
||||||
`internal/yaml` packages. Do not introduce dependencies, public API changes,
|
|
||||||
provider interfaces, configurable merge policies, or a generic visitor framework.
|
|
||||||
Private file splits do not require new packages or ADRs. Parser-specific types
|
|
||||||
must remain behind the existing YAML adapter boundary.
|
|
||||||
|
|
||||||
Preserve the implemented contracts, particularly:
|
|
||||||
|
|
||||||
- Strict composition remains distinct from intentional profile/CLI overlay.
|
|
||||||
- Input precedence, final-only typed decoding, retained defaults, canonical
|
|
||||||
decoding explanation events, and recorded domain resolution remain unchanged.
|
|
||||||
- Source identity, containment, optional-import rules, limits, diagnostic codes,
|
|
||||||
source coordinates, ordering, and early callback termination remain intact.
|
|
||||||
- Semantic paths retain explicit key/index distinctions and historical shapes.
|
|
||||||
- Returned values and inspection snapshots remain detached; secret values remain
|
|
||||||
absent from history, rendering, and library-generated diagnostics.
|
|
||||||
- Resolution runs before secret lookup and validation; ordinary loading never
|
|
||||||
bootstraps environment variables implicitly.
|
|
||||||
|
|
||||||
Use focused existing behavioral tests during each stage and the baseline checks
|
|
||||||
from the development guide before committing production changes. Add tests only
|
|
||||||
for meaningful gaps exposed by extraction, not to enforce file locations or
|
|
||||||
private call choreography. Update current owning documentation alongside each
|
|
||||||
move. The work lists below preserve the accepted scope; completion entries name
|
|
||||||
the implemented owners. Audit-baseline evidence describes the original layout.
|
|
||||||
Private implementation destinations are not new consumer contracts.
|
|
||||||
|
|
||||||
## Stage 1 — Remove unused overlay value snapshots
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: removed unread overlay before/after trees and their construction and
|
|
||||||
cloning, including the now-unused CLI position lookup. Field-read review confirmed
|
|
||||||
that resolution snapshots and history applications have separate live consumers;
|
|
||||||
those and displaced origins remain intact. The full offline test suite, vet,
|
|
||||||
build, and whitespace checks passed with Go 1.26.7 on Linux/amd64.
|
|
||||||
|
|
||||||
Audit-baseline evidence: `overlayRecord` in [overlay.go](../../overlay.go) retains `before` and
|
|
||||||
`after` trees; profile and CLI processing construct them and
|
|
||||||
`cloneOverlayRecords` clones them. Production consumers use the record's change
|
|
||||||
and displaced origins, while explanation uses `historyApplication` instead.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Reconfirm all field reads before removal. Remove only the unused overlay
|
|
||||||
snapshot fields and their construction/cloning in `overlay.go` and
|
|
||||||
[override.go](../../override.go).
|
|
||||||
2. Preserve `change`, `displaced`, input applications, and their ownership rules.
|
|
||||||
Do not remove resolution snapshots or retained decoded trees: those have
|
|
||||||
separate consumers and budget semantics.
|
|
||||||
3. Remove locals and imports made unnecessary by the deletion. Do not replace
|
|
||||||
the removed state with a new cache or history representation.
|
|
||||||
|
|
||||||
Acceptance: profile/CLI provenance, explanation replay, composition independence,
|
|
||||||
and redaction tests pass unchanged in observable behavior. Source inspection
|
|
||||||
confirms no unused overlay snapshot construction remains. An allocation benchmark
|
|
||||||
is not required to justify removing provably unread clones.
|
|
||||||
|
|
||||||
## Stage 2 — Centralize parser issue translation
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: `parserDiagnostics` in `parse.go` now owns detached, canonical
|
|
||||||
translation for selected, imported, and profile sources. Existing tests cover
|
|
||||||
safe selected-source errors and imported/profile source attribution, so no
|
|
||||||
duplicate regression was added. Full offline tests, vet, build, and whitespace
|
|
||||||
checks passed with Go 1.26.7 on Linux/amd64.
|
|
||||||
|
|
||||||
Audit-baseline evidence: [parse.go](../../parse.go) translates adapter issues inline, while
|
|
||||||
`importParseDiagnostics` in [imports.go](../../imports.go) repeats the translation
|
|
||||||
for imports and profiles.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Define one private `parserDiagnostics` helper in `parse.go` that maps adapter
|
|
||||||
issues to detached public diagnostics, including related locations.
|
|
||||||
2. Route selected-source, import, and profile parsing through it. Remove the
|
|
||||||
import-specific translator and keep upstream parser errors private.
|
|
||||||
3. Return canonically ordered diagnostics from the shared translation boundary.
|
|
||||||
Preserve existing codes, messages, primary/related coordinates, and source IDs.
|
|
||||||
Keep per-source parsing budgets and graph accounting at their current owners.
|
|
||||||
|
|
||||||
Acceptance: malformed selected/imported/profile input retains safe, correctly
|
|
||||||
attributed diagnostics. Use existing parser and import diagnostic tests; add a
|
|
||||||
small cross-entry regression only if a source path lacks equivalent coverage.
|
|
||||||
|
|
||||||
## Stage 3 — Share bounded regular-file read mechanics
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: `source_file.go` owns regular-file preflight/open/recheck/close and
|
|
||||||
bounded reads, with private failure kinds and stat/open-only optional-missing
|
|
||||||
classification. Callers retain containment, metadata, budgets, accounting, and
|
|
||||||
limit diagnostics. Existing filesystem, FIFO, budget, and reader tests pass;
|
|
||||||
a private regression covers nondeterministic filesystem failure phases. Full
|
|
||||||
offline baseline and race suites passed with Go 1.26.7 on Linux/amd64.
|
|
||||||
|
|
||||||
Audit-baseline evidence: `readSource`, `importTraversal.readImport`, and `readProfileFile` repeat
|
|
||||||
preflight stat, open, post-open stat, regular-file checks, size checks, and bounded
|
|
||||||
reads in [source.go](../../source.go), [imports.go](../../imports.go), and
|
|
||||||
[profile.go](../../profile.go).
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Introduce private helpers in `source_file.go` for regular-file opening and
|
|
||||||
bounded reading. Use narrow function parameters for stat/open operations so
|
|
||||||
callers can supply `os.Stat`/`os.Open` or root-bound methods. Do not introduce
|
|
||||||
an exported filesystem interface or substitute unrestricted opening for
|
|
||||||
`os.Root` access.
|
|
||||||
2. Keep preflight before open and post-open verification. Close every opened
|
|
||||||
file on all paths. Preserve the existing treatment of read-only file close
|
|
||||||
errors; root-directory close diagnostics are a separate responsibility.
|
|
||||||
3. Return private classified failures with enough distinction for callers to
|
|
||||||
map errors safely. Optional imports may suppress only the currently allowed
|
|
||||||
missing-target failures at stat/open, not later read failures. Do not expose
|
|
||||||
filesystem errors downstream through wrapping.
|
|
||||||
4. Keep source metadata, canonicalization, containment, per-source/aggregate
|
|
||||||
budgets, byte accounting, and caller-specific limit diagnostics outside the
|
|
||||||
shared mechanics. Pass the computed byte limit into the reader and retain
|
|
||||||
both the size precheck and limit-plus-one read enforcement.
|
|
||||||
5. Reuse bounded read mechanics for reader/byte sources only where it simplifies
|
|
||||||
existing code without changing single-use or ownership behavior. Keep secrets
|
|
||||||
bootstrap independent: its symlink, environment, and reporting policies differ.
|
|
||||||
|
|
||||||
Acceptance: source, import, profile, FIFO, containment, symlink, optional-missing,
|
|
||||||
exact-budget, and reader-ownership tests pass. Retain the deadline-isolated FIFO
|
|
||||||
regression. Cover private failure classification only where public tests cannot
|
|
||||||
reliably induce an important filesystem failure. Run race tests for this unit.
|
|
||||||
|
|
||||||
## Stage 4 — Establish shared document traversal ownership
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: `document_walk.go` owns nil-safe preorder value walking, borrowed
|
|
||||||
indexing, and semantic lookup. Metadata shapes and projected sensitivity use the
|
|
||||||
walker with defensive path copies. Specialized origins and budget traversals
|
|
||||||
remain explicit. Full offline tests (including historical path shapes, metadata
|
|
||||||
detachment, and dynamic secrets), vet, build, and whitespace checks passed with
|
|
||||||
Go 1.26.7 on Linux/amd64.
|
|
||||||
|
|
||||||
Audit-baseline evidence: `indexDocument`, `walkDocumentPaths`, and `projectedSensitivity` repeat
|
|
||||||
semantic tree traversal in [load_metadata.go](../../load_metadata.go),
|
|
||||||
[metadata.go](../../metadata.go), and [secret.go](../../secret.go). General document
|
|
||||||
lookup lived in [load.go](../../load.go).
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Create root-private `document_walk.go` with a nil-safe preorder walker taking
|
|
||||||
a starting `Path` and a callback receiving both path and node. Visit mappings
|
|
||||||
in stored order and sequences in index order; construct explicit Key/Index
|
|
||||||
segments. It visits value nodes, not synthetic mapping-key nodes.
|
|
||||||
2. Move `indexDocument` and `documentAtPath` to this owner. Implement indexing,
|
|
||||||
metadata shape collection, and projected sensitivity collection using the
|
|
||||||
walker where their traversal semantics match.
|
|
||||||
3. Document callback borrowing: callers must clone paths or nodes when retaining
|
|
||||||
mutable state. Preserve existing defensive copies and avoid sharing mutable
|
|
||||||
metadata across results.
|
|
||||||
4. Keep path-bearing helpers in the root package so `internal/document` does not
|
|
||||||
depend on the public package. Pure node representation and cloning stay in
|
|
||||||
`internal/document`.
|
|
||||||
5. Leave specialized traversals explicit where they need inherited origins,
|
|
||||||
pruning, node identity deduplication, or different counting. In particular,
|
|
||||||
input limits count mapping keys and retained-history limits count shared nodes
|
|
||||||
once; do not implement either using the new walker without those semantics.
|
|
||||||
|
|
||||||
Acceptance: numeric map keys versus sequence indices, escaped paths, unknown
|
|
||||||
paths, historical shape changes, deleted descendants, dynamic secret tags, and
|
|
||||||
metadata detachment remain protected by existing tests. No public path behavior
|
|
||||||
or predicate coverage changes. Do not add tests that assert walker call counts.
|
|
||||||
|
|
||||||
## Stage 5 — Separate typed projection, cloning, and comparison
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: projection, detached cloning, shared reflection state, and value-only
|
|
||||||
comparison now have separate owners. Named secret clone modes preserve the two
|
|
||||||
ownership barriers. Validation combines value and sensitivity comparison in a
|
|
||||||
named helper and separately audits resolved secret state. Standard `cmp.Compare`
|
|
||||||
replaces the custom comparator; tests changed only for private symbol renames.
|
|
||||||
Full offline baseline and race suites passed with Go 1.26.7 on Linux/amd64,
|
|
||||||
including codec/cycle/limit, callback ownership, sensitivity, and secret-state
|
|
||||||
regressions.
|
|
||||||
|
|
||||||
Audit-baseline evidence: [projection.go](../../projection.go) combines roughly 622 lines of
|
|
||||||
projection, detached cloning, dynamic schema handling, cycle/limit enforcement,
|
|
||||||
and structural comparison. Value equality deliberately ignores sensitivity,
|
|
||||||
which validation must check separately.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Keep canonical typed projection in `projection.go`; move cloning into
|
|
||||||
`clone.go`, shared reflection operation state and cycle helpers into
|
|
||||||
`value_operation.go`, and value-tree comparison into `document_compare.go`.
|
|
||||||
Preserve the descriptor-driven approach and per-operation schema cache.
|
|
||||||
2. Rename the private equality/comparison entry points to make configuration-value
|
|
||||||
semantics explicit. Document that location and sensitivity metadata are
|
|
||||||
excluded, mapping order is immaterial, and sequences are compared atomically
|
|
||||||
for change reporting. Update all callers without changing their semantics.
|
|
||||||
3. Give validator mutation comparison a named private owner in `validation.go`.
|
|
||||||
It must combine projected value changes and sensitivity changes, while
|
|
||||||
retaining private resolved-secret-state auditing as an additional check.
|
|
||||||
Do not make resolver value comparison start treating sensitivity as a value.
|
|
||||||
4. Preserve the distinction between cloning unresolved public secret references
|
|
||||||
and publication cloning of already validated private state. Name/document
|
|
||||||
the clone mode explicitly rather than leaving an unexplained boolean at
|
|
||||||
sensitive call sites.
|
|
||||||
5. Replace custom `cmpString` calls with the standard library comparator and
|
|
||||||
remove that helper. Do not perform unrelated test-style rewrites.
|
|
||||||
|
|
||||||
Acceptance: projection/cloning tests cover nil versus empty, custom text codecs,
|
|
||||||
inline fields, dynamic types, cycles, and limits. Validator mutation regressions
|
|
||||||
must still reject equal-text sensitivity changes and secret-state changes.
|
|
||||||
Callback ownership and secret lookup tests must prove publication does not share
|
|
||||||
borrowed values or reread the environment. Run race tests for this unit.
|
|
||||||
|
|
||||||
## Stage 6 — Clarify source assembly and override ownership
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: filesystem context/canonicalization/containment moved to
|
|
||||||
`filesystem.go`; directive parsing and restrictions moved to `directives.go`;
|
|
||||||
input node counting now shares the document owner with explicit key accounting.
|
|
||||||
Override preparation, parser-neutral value building, and application are separate;
|
|
||||||
profile and CLI application share the composition clone. Deferred profile cleanup
|
|
||||||
preserves primary failures and explicitly checks the success-path close once.
|
|
||||||
Full offline tests, vet, build, and whitespace checks passed with Go 1.26.7 on
|
|
||||||
Linux/amd64, including imports/globs, profiles, CLI, limits, and provenance.
|
|
||||||
|
|
||||||
Audit-baseline evidence: [imports.go](../../imports.go) mixes filesystem context, directives,
|
|
||||||
graph traversal, and diagnostics; [override.go](../../override.go) combines value
|
|
||||||
construction/validation and application. Shared composition cloning is located
|
|
||||||
inside the override feature, while profile overlay repeats it.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Keep import traversal and route diagnostics in `imports.go`. Move filesystem
|
|
||||||
context validation/canonicalization/containment to `filesystem.go`, and
|
|
||||||
directive structures/parsing/fragment restrictions to `directives.go`.
|
|
||||||
Give source-independent node counting an appropriate shared document owner,
|
|
||||||
with its mapping-key accounting documented.
|
|
||||||
2. Keep override validation and preparation in `override.go`, move parser-neutral
|
|
||||||
value building to `override_value.go`, and application/displacement mechanics
|
|
||||||
to `override_apply.go`.
|
|
||||||
3. Move `cloneComposedDocument` next to `composedDocument` in `compose.go`; use it
|
|
||||||
for both profile overlay and overrides. Ensure every retained field is copied
|
|
||||||
according to its existing ownership contract.
|
|
||||||
4. Keep strict composition, overlay, and history replay separate. Share small
|
|
||||||
mechanics when identical; do not introduce merge strategy flags or one general
|
|
||||||
merge engine. Preserve the existing profile-versus-CLI recording behavior.
|
|
||||||
5. Simplify profile root cleanup using deferred failure-path cleanup plus an
|
|
||||||
explicit checked success-path close. Preserve primary failure diagnostics and
|
|
||||||
the existing successful-read root-close error diagnostic; avoid double-close
|
|
||||||
effects. Import traversal cleanup may remain explicit where already clear.
|
|
||||||
|
|
||||||
Acceptance: imports/globs, directive restrictions, source ordering, profiles,
|
|
||||||
overrides, version restrictions, limits, and composition independence tests pass.
|
|
||||||
No new cross-package dependencies appear. Root handles close on every path and
|
|
||||||
profile/CLI provenance remains identical.
|
|
||||||
|
|
||||||
## Stage 7 — Extract explicit loader lifecycle phases
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: `load.go` now visibly coordinates ordered phases using source assembly
|
|
||||||
in `load_input.go`, option selection in `options.go`, and typed phase outputs and
|
|
||||||
publication in `load_result.go`. Version checking lives in `validation.go`.
|
|
||||||
One composition initializer covers profiles, CLI, and NoSource overrides without
|
|
||||||
changing budgets. Diagnostics and source handoffs remain explicit, both ownership
|
|
||||||
clones remain, and publication adds no history copies. Full offline baseline and
|
|
||||||
race suites passed with Go 1.26.7 on Linux/amd64; lifecycle, early-stop, warning,
|
|
||||||
precedence, provenance, callback ownership, and secret tests passed unchanged.
|
|
||||||
|
|
||||||
Audit-baseline evidence: `loadWithSecretLookup` in [load.go](../../load.go) coordinates roughly
|
|
||||||
200 lines of source assembly, decoding, callbacks, history, secrets, and result
|
|
||||||
publication, including repeated creation of a composition handoff.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Keep the exported entry point and a readable linear coordinator in `load.go`.
|
|
||||||
Move option selection to `options.go`, input assembly to `load_input.go`, and
|
|
||||||
typed lifecycle/result publication to `load_result.go`. Move version checking
|
|
||||||
beside the validation machinery rather than keeping it among document helpers.
|
|
||||||
2. Use small private handoff structs for assembled input and necessary phase
|
|
||||||
outputs, not a mutable all-purpose loader object or a long list of output
|
|
||||||
parameters. Reuse one composition initialization helper for profile and CLI
|
|
||||||
processing, including NoSource override handling and source byte/node totals.
|
|
||||||
3. Preserve the exact existing order of option validation, parsing/import checks,
|
|
||||||
schema validation, version checking, profile/CLI application, defaults factory,
|
|
||||||
typed decoding, resolution, retained-history limit enforcement, secret lookup,
|
|
||||||
validation, metadata/classification, and result publication.
|
|
||||||
4. Keep diagnostic/source accumulation explicit. Warnings survive successful
|
|
||||||
phases; errors stop dependent work and never return a usable partial Result.
|
|
||||||
5. Preserve both ownership barriers: detach resolver-borrowed values before secret
|
|
||||||
resolution and validation, then detach equal-valued validator replacements
|
|
||||||
before publication while preserving validated secret state. Do not remove
|
|
||||||
either clone as apparently redundant work.
|
|
||||||
6. Group Result's frozen inspection state only if it clarifies this handoff; do
|
|
||||||
not add an additional history copy or change caller ownership of Config.
|
|
||||||
|
|
||||||
Acceptance: lifecycle ordering/early-stop tests, defaults-only loading, all input
|
|
||||||
combinations, callback ownership, secrets, warning retention, and complete
|
|
||||||
provenance agreement pass. Keep orchestration visible enough to verify phase
|
|
||||||
ordering by reading the coordinator. Run the complete race suite.
|
|
||||||
|
|
||||||
## Stage 8 — Separate explanation replay, snapshots, and rendering
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion: public records and Explain coordination remain in `explain.go`;
|
|
||||||
immutable applications, replay/coalescing, and shared-node budgeting live in
|
|
||||||
`history.go`; shared effective/explanation redaction lives in `snapshot.go`;
|
|
||||||
human output lives in `explain_render.go`. Metadata versus replay ownership is
|
|
||||||
documented beside history. Existing reconciliation, historical sensitivity,
|
|
||||||
container/leaf, retained-budget, detachment, and writer-failure tests passed
|
|
||||||
without expectation changes. Full offline tests, vet, build, and whitespace
|
|
||||||
checks passed with Go 1.26.7 on Linux/amd64.
|
|
||||||
|
|
||||||
Audit-baseline evidence: [explain.go](../../explain.go) combines approximately 576 lines of public
|
|
||||||
records, replay algorithms, snapshot redaction, retained-history accounting, and
|
|
||||||
human-readable output.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Keep public explanation records and Explain coordination in `explain.go`.
|
|
||||||
Move application/snapshot replay and history budgeting to `history.go`, safe
|
|
||||||
snapshot projection to `snapshot.go`, and WriteExplanation with its formatting
|
|
||||||
helpers to `explain_render.go`.
|
|
||||||
2. Make effective rendering and explanation snapshots use the existing shared
|
|
||||||
redaction implementation; do not create separate sensitivity rules.
|
|
||||||
3. Retain the canonical decoding reconciliation event between input replay and
|
|
||||||
domain resolution, overlapping resolution intent coalescing, added/deleted
|
|
||||||
paths, effective source attribution, and historical secret classification.
|
|
||||||
4. Document the differences between metadata origin records and value replay:
|
|
||||||
they serve different query contracts but must agree on effective results.
|
|
||||||
Do not replace them with a new event-store abstraction in this cleanup.
|
|
||||||
5. Preserve writer failure behavior and ownership of retained trees. Do not cache
|
|
||||||
explanations or optimize full-tree replay without measured need.
|
|
||||||
|
|
||||||
Acceptance: explanation, effective rendering, history budget, provenance, secret
|
|
||||||
redaction, and writer-failure tests pass without output changes. Container and
|
|
||||||
leaf histories still reconcile with the frozen effective typed configuration.
|
|
||||||
|
|
||||||
## Stage 9 — Complete ownership documentation and integration validation
|
|
||||||
|
|
||||||
Status: complete.
|
|
||||||
|
|
||||||
Completion evidence (2026-09-07):
|
|
||||||
|
|
||||||
- Reviewed the final owners and accumulated diff against starting revision
|
|
||||||
`874adaa`. Removed the unused `cloneResolutionSnapshots` helper and an unused
|
|
||||||
resolution lookup binding; live resolution snapshots and replay budgets remain.
|
|
||||||
Shared parser translation and document walking have one owner, while specialized
|
|
||||||
origin, pruning, and shared-node accounting remain explicit.
|
|
||||||
- Updated the [component overview](../internal/overview.md), repaired moved-owner
|
|
||||||
navigation in the extraction and implementation records, and distinguished
|
|
||||||
baseline findings from completion evidence here. The overview now accurately
|
|
||||||
describes populated metadata queries and the retained dependency direction.
|
|
||||||
- An independent Go AST comparison found all 186 root-package exported
|
|
||||||
declarations unchanged from `874adaa`. Function-level review ignoring file moves
|
|
||||||
matched the planned extractions, consolidation, and private renames. Existing
|
|
||||||
behavioral assertions remain unchanged; no API, configuration, diagnostic,
|
|
||||||
dependency, or consumer migration change was identified.
|
|
||||||
- The complete source checker passed on native Linux/amd64 with CGO enabled,
|
|
||||||
using these exact cached toolchains:
|
|
||||||
|
|
||||||
```sh
|
|
||||||
CONFIGKIT_BASELINE_TOOLCHAIN=go1.25.5 CONFIGKIT_NEWER_TOOLCHAIN=go1.26.7 ./scripts/release-check.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
This ran offline default tests, vet, and native builds on Go 1.25.5 and Go 1.26.7;
|
|
||||||
the full race suite on Go 1.26.7; disposable-copy module hygiene; formatting and
|
|
||||||
whitespace; executable examples and consumer fixtures; local documentation
|
|
||||||
links and the AST import-boundary gate; and CGO-disabled cross-builds for
|
|
||||||
Linux/macOS on amd64/arm64. All passed; `go.mod` and `go.sum` are unchanged.
|
|
||||||
- Fresh verbose Linux filesystem checks passed without skips for selected/imported/
|
|
||||||
profile FIFO rejection, symlink containment, hard-link identity, optional missing
|
|
||||||
targets, directory permission failures, and the new private read-failure phase
|
|
||||||
regression. Package import inspection confirmed `internal/document` has no
|
|
||||||
imports and only `internal/yaml` imports the upstream YAML package.
|
|
||||||
- Native macOS and native arm64 execution were unavailable on this Linux/amd64
|
|
||||||
host. Cross-builds do not close those execution gaps. Exact candidate validation,
|
|
||||||
roadmap retirement, release-note review, remote/tag guards, and post-publication
|
|
||||||
retrieval remain owned by the [release procedure](../release.md) and
|
|
||||||
[readiness record](release-readiness.md). No tag, push, or publication occurred.
|
|
||||||
|
|
||||||
Work:
|
|
||||||
|
|
||||||
1. Review the final code for obsolete helpers, duplicate traversal/translation,
|
|
||||||
unread retained state, stale comments, and imports left by earlier stages.
|
|
||||||
Confirm file splits reflect discrete responsibilities rather than line quotas.
|
|
||||||
2. Update the component overview to describe the actual owners and fix its stale
|
|
||||||
claim that metadata queries are empty. Keep detailed consumer semantics in
|
|
||||||
their existing contract; repair navigation and moved-file links throughout
|
|
||||||
documentation, including this roadmap's evidence links if necessary.
|
|
||||||
3. State the retained dependency direction clearly: public lifecycle coordination
|
|
||||||
uses private source/document/schema/inspection helpers; the owned document
|
|
||||||
representation has no dependency on the root package; only the private YAML
|
|
||||||
adapter imports the upstream YAML package.
|
|
||||||
4. Run the full baseline and race suites, local documentation and dependency
|
|
||||||
boundary checks, and the complete source-candidate checker described in the
|
|
||||||
release procedure with available qualifying toolchains. Record exact versions,
|
|
||||||
host platform, results, and any unavailable platform evidence. Cross-builds
|
|
||||||
are not native execution evidence.
|
|
||||||
5. Review the accumulated diff for public API/configuration/diagnostic changes.
|
|
||||||
Expected outcome: no consumer migration or dependency change. If any contract
|
|
||||||
change is discovered, resolve it explicitly before closing this roadmap.
|
|
||||||
6. Record completion evidence and commit this final nonempty unit. Release
|
|
||||||
preparation must subsequently retire completed roadmap material and validate
|
|
||||||
the exact committed candidate under release policy. Completing this roadmap
|
|
||||||
does not create a tag, push refs, or authorize publication.
|
|
||||||
|
|
||||||
Acceptance: all stages are complete with recorded validation, existing behavioral
|
|
||||||
regressions remain protected, documentation matches the new ownership layout,
|
|
||||||
and the worktree is clean after commits. Required release gates remain visible
|
|
||||||
in the release procedure rather than being declared satisfied by this refactor.
|
|
||||||
|
|
||||||
## Open Questions
|
|
||||||
|
|
||||||
None required to begin implementation. The package boundaries, compatibility
|
|
||||||
constraints, ordered units, and acceptance criteria above are decided. Routine
|
|
||||||
private naming adjustments are acceptable when they preserve those decisions;
|
|
||||||
new behavioral discoveries require explicit evidence and disposition.
|
|
||||||
Reference in New Issue
Block a user