eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare source release validation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-06 22:47:12 +00:00
parent 2836f825b6
commit f42ecc70c3
21 changed files with 721 additions and 1205 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
docs/roadmap/implementation.md
View File

@@ -2,8 +2,8 @@
## Status and ownership
Status: implementation in progress; Stages 1–15 are complete and later stages are
pending.
Status: implementation complete; Stages 1–22 are complete. Release-candidate
selection and publication remain separate maintainer work.
Audience: a `gpt-5.6-terra` coding agent implementing one stage per prompt, in
ascending order. Each stage depends on every earlier stage being complete.
@@ -85,7 +85,7 @@ the adapter, YAML-policy, diagnostics, limits, and rendering regressions. A fina
upstream version is preferred when it passes those checks; if the RC is retained,
record that decision in release readiness and compatibility review.
Follow the feature's [upstream isolation contract](initial.md#yaml-dependency-and-public-api-isolation).
Follow the feature's [upstream isolation contract](../policy/architecture.md#public-api-and-dependency-direction).
Translate upstream API changes internally without changing ConfigKit declarations
or consumer requirements. Never re-export upstream aliases/options/plugins, expose
parser errors through wrapping, or pass parser-created objects through `any`.
@@ -97,8 +97,8 @@ unverified upstream versions or add a selectable-parser framework.
### Updated extraction map
Use the source revisions and adaptation policies owned by the feature's
[foundation](initial.md#existing-implementation-foundation) and
[secret bootstrap](initial.md#secret-references-and-explicit-bootstrap) sections.
[foundation](../internal/extraction.md) and
[secret bootstrap](../config.md#typed-secret-references) sections.
Paths below are relative to the named sibling repository. Reinspect them in
Stage 1 and record the exact revision actually copied. The maintainer is the sole
author of the relevant application code and has authorized its reuse and relicensing
@@ -154,9 +154,9 @@ syscall-level confinement, path discovery, or a public filesystem-provider API.
### Secret, override, and history implementation bounds
Follow the feature contracts for [secrets](initial.md#secret-references-and-explicit-bootstrap),
[CLI overrides](initial.md#cli-overrides), and
[explanation](initial.md#historical-value-explanation). Introduce these public APIs
Follow the feature contracts for [secrets](../config.md#typed-secret-references),
[CLI overrides](../config.md#explicit-cli-overrides), and
[explanation](../config.md#historical-value-explanation). Introduce these public APIs
only in Stages 16–19. Earlier stages cover ordinary types and file/profile layers;
they must not expose an unresolved secret as a completed load or silently accept
an override option. Extend the shared descriptor/projection graph for `Secret`
@@ -303,8 +303,8 @@ Completion evidence (2026-09-06):
No deviations were required. Paths, diagnostics, parsing, and all later behavior
remain assigned to subsequent stages.
Read: feature [foundation](initial.md#existing-implementation-foundation),
[consumer fit](initial.md#consumer-fit-and-intentional-migrations), all policies.
Read: feature [foundation](../internal/extraction.md),
[consumer fit](../consumers/README.md), all policies.
Tasks:
@@ -353,8 +353,8 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
metadata population and configuration lifecycle behavior remain later work.
Read: feature [paths](initial.md#paths-and-presence),
[diagnostics](initial.md#provenance-diagnostics-and-redaction), public metadata API.
Read: feature [paths](../config.md#layered-metadata),
[diagnostics](../config.md#safe-failures), public metadata API.
Tasks:
@@ -408,8 +408,8 @@ Completion evidence (2026-09-06):
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64. No
deviations were required; typed binding and decoding remain later work.
Read: feature [YAML policy](initial.md#yaml-and-scalar-policy),
[source constructors](initial.md#entry-point-and-reusable-application-definition).
Read: feature [YAML policy](../config.md#yaml-documents),
[source constructors](../config.md#single-source-loading).
Start with the extraction map's parser and strict-loader cases; the old
second-document acceptance defect is already fixed in Narratio.
@@ -485,8 +485,8 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
typed value operations remain later work.
Read: feature [typed decoding](initial.md#typed-decoding) and
[type/projection contract](initial.md#supported-types-and-projection).
Read: feature [typed decoding](../config.md#defaults-and-typed-decoding) and
[type/projection contract](../config.md#application-schema-binding).
Tasks:
@@ -537,8 +537,8 @@ Completion evidence (2026-09-06):
Go 1.26.7 on linux/amd64. No deviations were required; defaults and typed decoding
remain later work.
Read: feature [ownership](initial.md#recorded-resolution-and-validation) and
[type/projection contract](initial.md#supported-types-and-projection).
Read: feature [ownership](../config.md#recorded-application-resolution) and
[type/projection contract](../config.md#application-schema-binding).
Tasks:
@@ -590,7 +590,7 @@ Completion evidence (2026-09-06):
and `git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
public loading and schema-version checks remain later work.
Read: feature [defaults/null](initial.md#static-defaults-and-null) and typed decoding.
Read: feature [defaults/null](../config.md#defaults-and-typed-decoding) and typed decoding.
Tasks:
@@ -651,9 +651,9 @@ Completion evidence (2026-09-06):
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64. No
deviations were required; resolution and semantic validation remain later work.
Read: feature [lifecycle](initial.md#resolution-lifecycle),
[version hook](initial.md#schema-checking-and-secret-classification),
[results](initial.md#results-errors-and-inspection).
Read: feature [lifecycle](../config.md#single-source-loading),
[version hook](../config.md#application-schema-binding),
[results](../config.md#safe-failures).
Tasks:
@@ -715,7 +715,7 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
semantic validation remains later work.
Read: feature [resolution callbacks](initial.md#resolution-and-validation-callbacks).
Read: feature [resolution callbacks](../config.md#recorded-application-resolution).
Tasks:
@@ -776,8 +776,8 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
imports and profiles remain deliberately unavailable.
Read: feature [diagnostic callbacks](initial.md#resolution-and-validation-callbacks)
and [schema reports](initial.md#schema-checking-and-secret-classification).
Read: feature [diagnostic callbacks](../config.md#recorded-application-resolution)
and [schema reports](../config.md#application-schema-binding).
Tasks:
@@ -824,7 +824,7 @@ Completion evidence (2026-09-06):
[current composition contract](../config.md#strict-document-composition) owns the
implemented semantics; public import wiring remains deferred to subsequent work.
Read: feature [composition table](initial.md#composition-and-overlay).
Read: feature [composition table](../config.md#strict-document-composition).
Extract Narratio's additive composer and conflict tests before writing equivalent
code. Change empty-map expectations to the feature table and retain exact locations.
@@ -883,7 +883,7 @@ Completion evidence (2026-09-06):
`go test -race ./...`, `go vet ./...`, `go build ./...`, `go mod tidy -diff`, and
`git diff --check` with Go 1.26.7 on linux/amd64.
Read: feature [import graph](initial.md#explicit-imports-and-source-identity).
Read: feature [import graph](../config.md#explicit-imports).
Extract the flat import loader and tests, then generalize its graph, identity and
containment rules. Do not treat its root-only declarations as ConfigKit's contract.
@@ -1008,7 +1008,7 @@ Completion evidence (2026-09-06):
Verified `go test ./...`, `go test -race ./...`, `go vet ./...`, `go build ./...`,
and `git diff --check` with Go 1.26.7 on linux/amd64.
Read: feature [profiles](initial.md#profiles), composition/overlay table.
Read: feature [profiles](../config.md#selected-profiles), composition/overlay table.
Extract Narratio's overlay mechanics and profile tests; preserve the intentional
null/kind and profile-selection differences listed in the feature roadmap.
@@ -1064,8 +1064,8 @@ Completion evidence (2026-09-06):
Verified `go test ./...`, `go test -race ./...`, `go vet ./...`, `go build ./...`,
`go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on linux/amd64.
Read: feature [presence](initial.md#paths-and-presence),
[history](initial.md#provenance-diagnostics-and-redaction), metadata API.
Read: feature [presence](../config.md#layered-metadata),
[history](../config.md#safe-failures), metadata API.
Use Narratio's effective ownership and inspection tests as extraction evidence.
Its source-only records need locations and complete historical operations.
@@ -1123,8 +1123,8 @@ Completion evidence (2026-09-06):
`go build ./...`, `go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on
linux/amd64.
Read: feature [redaction](initial.md#provenance-diagnostics-and-redaction),
[secret predicate](initial.md#schema-checking-and-secret-classification), result API.
Read: feature [redaction](../config.md#safe-failures),
[secret predicate](../config.md#application-schema-binding), result API.
Reuse Narratio's deterministic effective-output and non-disclosure cases. Render
from the owned typed projection, without its marshal/parse reconstruction.
@@ -1195,7 +1195,7 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
environment-backed typed secret references remain later work.
Read: [secret bootstrap contract](initial.md#secret-references-and-explicit-bootstrap),
Read: [secret bootstrap contract](../config.md#typed-secret-references),
architecture responsibility boundary, testing policy, and WeatherReporter's
`internal/config/secrets.go` and corresponding `config_test.go` cases; also
Narratio's `internal/app/secrets_env.go`, its tests, and bounded-read helper.
@@ -1267,7 +1267,7 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
CLI overrides remain later work.
Read: [secret reference contract](initial.md#secret-references-and-explicit-bootstrap),
Read: [secret reference contract](../config.md#typed-secret-references),
shared descriptor/projection rules and lifecycle, Stage 16 report boundary.
Tasks:
@@ -1337,7 +1337,7 @@ Completion evidence (2026-09-06):
`git diff --check` with Go 1.26.7 on linux/amd64. No deviations were required;
safe historical-value explanation remains later work.
Read: [override contract](initial.md#cli-overrides), overlay/presence/version rules,
Read: [override contract](../config.md#explicit-cli-overrides), overlay/presence/version rules,
source ordering, and the secret-reference boundary.
Tasks:
@@ -1403,7 +1403,7 @@ Completion evidence (2026-09-06):
`go build ./...`, `go mod tidy -diff`, and `git diff --check` with Go 1.26.7 on
linux/amd64. No deviations were required; consumer ergonomics remain later work.
Read: [explanation contract](initial.md#historical-value-explanation), redaction
Read: [explanation contract](../config.md#historical-value-explanation), redaction
rules, and history bounds above.
Generalize Narratio's semantic-record and inspection tests. They cover effective
@@ -1598,7 +1598,47 @@ Acceptance:
## Stage 22 — Prepare release validation and reconcile documentation
Status: pending.
Status: complete.
Completion evidence (2026-09-06):
- Added the [maintainer release procedure](../release.md) for the existing
`origin/main`, module `gitea.maximumdirect.net/eric/ConfigKit`, source-only stable
tags, Go 1.25 minimum and newer-toolchain validation, and Linux/macOS amd64/arm64
targets. It supplies candidate recording, clean branch/index/worktree and exact
remote-commit guards, version/release-note/tag checks, precise single-ref tag
publication, clean consumer retrieval without `replace`, and immutable correction
steps. Private-host access is a prerequisite without embedding credentials or
environment dumps.
- Added fail-fast [`scripts/release-check.sh`](../../scripts/release-check.sh). It
verifies cached dependencies and runs offline disposable-copy module hygiene,
default tests on Go 1.25.5 and Go 1.26.7, vet and native builds on both, a native
race run, CGO-disabled builds for linux/amd64, linux/arm64, darwin/amd64, and
darwin/arm64, repository-wide Go formatting and text whitespace including
untracked files, executable examples, consumer fixtures, public import isolation,
and local documentation links. Toolchain/dependency acquisition remains an
explicit preceding runbook step.
- Added `TestLocalDocumentationLinks`, which strictly verifies repository-local files
and Markdown headings while treating recorded sibling-source links as applicable
only when those optional checkouts exist. The runbook makes immutable extraction
revisions authoritative in isolated release clones.
- Reconciled README, development, configuration, consumer, architecture/testing/
documentation/release policies, component and extraction inventories, and ADR
navigation with current behavior. Reduced the implemented feature roadmap to a
target record linking current owners and retaining only foundations plus explicit
non-goals/deferred scope. The implementation plan and readiness record remain until
an actual candidate retires completed roadmap files as required by release policy.
- Reassessed the YAML v4 dependency with `go list -m -versions` and
`go list -m -json ...@latest`; `v4.0.0-rc.6` remained the newest available release
on 2026-09-06, so the tested explicit pin was retained. `go doc -all` and
`TestDependencyImportBoundary` confirmed public documentation is renderable and no
upstream YAML type/import leaks outside the private adapter or maintained examples.
- The complete checker passed on linux/amd64 with Go 1.25.5 and Go 1.26.7. The
[release-readiness evidence](release-readiness.md) keeps exact candidate/release
note, native macOS execution, compatibility/content approval, roadmap retirement,
authoritative remote/tag guards, and post-publication retrieval explicitly open
under the revised bootstrap exception. No tag, push, downstream migration, release
note, or publication occurred.
Read: release policy in full and [release-readiness gaps](release-readiness.md).