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
|
||||
[consumer adoption guide](docs/consumers/README.md) provides maintained Narratio-,
|
||||
Notarius-, WeatherReporter-, and Seriatim-shaped examples and migration guidance.
|
||||
The [initial target record](docs/roadmap/initial.md) links implemented feature owners
|
||||
and preserves deliberately deferred scope. The [implementation plan](docs/roadmap/implementation.md)
|
||||
records completion evidence until release-candidate preparation retires it. See the
|
||||
The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions. See the
|
||||
[development guide](docs/development.md) for repository orientation and the
|
||||
[release procedure](docs/release.md) for maintainer-only candidate and publication
|
||||
steps.
|
||||
|
||||
@@ -18,7 +18,7 @@ public behavior.
|
||||
| --- | --- |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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) |
|
||||
@@ -31,9 +31,16 @@ Accepted decisions:
|
||||
- [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)
|
||||
|
||||
For cross-cutting changes, follow every applicable row. The
|
||||
[implementation plan](roadmap/implementation.md) owns the ordered stages and their
|
||||
acceptance checks and recorded implementation evidence.
|
||||
For cross-cutting changes, follow every applicable row. Completed implementation
|
||||
and remediation plans are preserved in Git history at `cb5b435`; use current
|
||||
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
|
||||
|
||||
@@ -81,14 +88,14 @@ code changes. Use the component overview to find the corresponding implementatio
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
| 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'` |
|
||||
|
||||
## Fuzz validation
|
||||
|
||||
@@ -59,7 +59,8 @@ representations private. The implemented components and their owners are:
|
||||
`internal/yaml/write.go`;
|
||||
- a separate maintained `examples/consumers` package with four sanitized consumer
|
||||
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.
|
||||
|
||||
Dependency direction remains inward: the public lifecycle coordinates private
|
||||
@@ -82,7 +83,7 @@ implementation:
|
||||
- [Extraction inventory](extraction.md)
|
||||
|
||||
The [architecture policy](../policy/architecture.md) owns binding boundaries and
|
||||
invariants. The [initial target record](../roadmap/initial.md) links current feature
|
||||
owners and preserves deferred scope; it is not an implementation inventory. See the
|
||||
invariants. The [deferred scope](../roadmap/deferred.md) records deliberate
|
||||
exclusions. See the
|
||||
[development guide](../development.md) for contributor orientation and validation
|
||||
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.
|
||||
The [component overview](../internal/overview.md) owns implementation inventory, 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
|
||||
|
||||
@@ -136,7 +136,7 @@ for safe messages supplied by their hooks.
|
||||
Do not introduce automatic directory discovery, network providers, arbitrary
|
||||
merge strategies, additional configuration languages, or application runtime
|
||||
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
|
||||
changes require an ADR and corresponding policy/contract updates; implementation
|
||||
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.
|
||||
- Roadmaps own unimplemented targets, deferred work, and execution status.
|
||||
|
||||
The initial target and implementation plan have separate owners. Do not put
|
||||
staged steps or progress in `docs/roadmap/initial.md`. `docs/roadmap/implementation.md` owns those details.
|
||||
Future implementation plans own their task order, acceptance gates, and progress;
|
||||
`docs/roadmap/deferred.md` owns deliberate exclusions, not execution instructions.
|
||||
As behavior lands, move its normative definition into the current contract and
|
||||
replace the roadmap definition with a link. Retire completed roadmap material
|
||||
as part of release preparation; ADRs preserve significant decision history.
|
||||
@@ -56,7 +56,7 @@ handling, not secret values.
|
||||
|
||||
| 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 |
|
||||
| Architecture rules | `docs/policy/architecture.md` | Responsibilities, dependency constraints, invariants, and scope boundaries |
|
||||
| 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 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| 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 |
|
||||
| Implementation plan | `docs/roadmap/implementation.md` | Stages, dependencies, acceptance gates, and progress |
|
||||
| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and the conditions for reconsidering them |
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
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
|
||||
preparing the first release owns the remaining gates under the
|
||||
[temporary bootstrap exception](../policy/release.md#temporary-bootstrap-deferral).
|
||||
This evidence record remains until candidate preparation retires completed roadmap
|
||||
material in favor of the operational [release procedure](../release.md) and normal
|
||||
release notes.
|
||||
Completed implementation, remediation, and initial-target records have retired to
|
||||
Git history at `cb5b435`. [Deferred scope](deferred.md) remains separate. This
|
||||
record retains preparation evidence and unresolved release gates until their
|
||||
closure is recorded under the operational [release procedure](../release.md).
|
||||
|
||||
## 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. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
@@ -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. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
| 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