320 lines
19 KiB
Markdown
320 lines
19 KiB
Markdown
|
|
# ConfigKit v0.5.0 implementation plan
|
||
|
|
|
||
|
|
## Scope and authority
|
||
|
|
|
||
|
|
Implement [the ConfigKit roadmap](config.md). It owns the target, compatibility
|
||
|
|
choices, and rationale. This plan covers Narratio's upgrade from v0.4.2 to
|
||
|
|
v0.5.0 and integration with native sibling inheritance. Audita adoption and
|
||
|
|
workspace reorganization remain subsequent, separately planned work.
|
||
|
|
|
||
|
|
The reviewed upstream revision is
|
||
|
|
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`.
|
||
|
|
Use the released module, not a local replacement. The pinned
|
||
|
|
[configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md)
|
||
|
|
and [consumer guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md)
|
||
|
|
own upstream semantics. Read their sibling-inheritance and metadata sections
|
||
|
|
when working on the relevant stages; source may also be inspected in the
|
||
|
|
selected Go module cache. The sibling checkout is optional reference material,
|
||
|
|
not a build or test dependency.
|
||
|
|
|
||
|
|
## Working instructions
|
||
|
|
|
||
|
|
The audience is a Luna coding agent. Complete the numbered stages in order.
|
||
|
|
Each stage is a bounded unit with its own verification and completion criteria.
|
||
|
|
Inspect current code before editing; the paths below identify owners rather
|
||
|
|
than requiring changes to every listed file.
|
||
|
|
|
||
|
|
- Start with `docs/development.md`, `docs/policy/agents.md`, and `config.md` in
|
||
|
|
this directory. Follow the development policy-reading guide. Architecture,
|
||
|
|
testing, documentation, and OSS policies apply to this work; release policy
|
||
|
|
applies if discussing compatibility or eventual release preparation.
|
||
|
|
- Use Go 1.26. Prefer the repository's graph tools for code discovery and
|
||
|
|
inspect focused tests at each package boundary.
|
||
|
|
- Keep ordinary `Load`, typed defaults, explicit imports, one selected overlay,
|
||
|
|
domain validation, and current path-resolution rules. Native inheritance is
|
||
|
|
available wherever ConfigKit and Narratio's schema permit it, with no new
|
||
|
|
collection allowlist, opt-in flag, or Narratio-owned inheritance engine.
|
||
|
|
- Distinguish original declarations from inherited contributors. Preserve
|
||
|
|
genuine duplicate-base rejection and truthful provenance. Parent entries
|
||
|
|
remain ordinary entries subject to existing domain rules.
|
||
|
|
- Keep invocation-owned secrets bootstrap and shared exact-name credential
|
||
|
|
forwarding unchanged. Do not introduce a second base load, file reparse, or
|
||
|
|
historical-secret lookup to recover declaration information.
|
||
|
|
- Tests use temporary files, controlled synthetic secrets, and real internal
|
||
|
|
collaborators. No downstream executable, sibling checkout, cloud service,
|
||
|
|
or paid provider is needed. Protect integration behavior rather than
|
||
|
|
duplicating ConfigKit's generic algorithm tests or freezing incidental output.
|
||
|
|
- Commit each completed nonempty unit with a short plain-English message after
|
||
|
|
suitable validation. Report blockers and incomplete work accurately. If a
|
||
|
|
review-only task needs no source fix, retain useful behavioral coverage and
|
||
|
|
report that result rather than making a cosmetic rewrite.
|
||
|
|
|
||
|
|
Do not adopt layered loading, new source types, source-relative rebasing,
|
||
|
|
abstract artifacts, automatic YAML conversion, new execution selection rules,
|
||
|
|
new output collision policy, or changes to subprocess credentials and workspace
|
||
|
|
paths in this feature. Existing domain validation and reuse rules still apply;
|
||
|
|
do not add prohibitions, hardening, or guarantees merely because they can be
|
||
|
|
tested. This plan does not authorize a release, push, tag, ADR acceptance, or
|
||
|
|
retirement of pending roadmaps.
|
||
|
|
|
||
|
|
## Stage 1: Select the released dependency and update attribution
|
||
|
|
|
||
|
|
Purpose: establish the actual dependency baseline before integration work.
|
||
|
|
|
||
|
|
Read `go.mod`, `go.sum`, `docs/oss/attribution.md`, the OSS policy, and the
|
||
|
|
selected release's notes, `COPYRIGHT`, and `LICENSE`.
|
||
|
|
|
||
|
|
1. Select `gitea.maximumdirect.net/eric/ConfigKit@v0.5.0` with the normal Go
|
||
|
|
module workflow. Keep Go 1.26 and avoid unrelated dependency upgrades.
|
||
|
|
2. Update ConfigKit's attribution entry to v0.5.0 and use the full reviewed
|
||
|
|
commit for its Source, COPYRIGHT, and LICENSE links. Preserve upstream
|
||
|
|
copyright wording, SPDX expression, and applicable local license links.
|
||
|
|
Its license and YAML dependency are unchanged; no new license copy is needed.
|
||
|
|
3. Inspect module changes for unintended churn or a local `replace`. Existing
|
||
|
|
configuration loaders should compile without adopting optional APIs.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config ./internal/app ./internal/doccheck`
|
||
|
|
and `go mod tidy -diff`. Confirm
|
||
|
|
`go list -m gitea.maximumdirect.net/eric/ConfigKit` selects v0.5.0 without a
|
||
|
|
replacement.
|
||
|
|
|
||
|
|
Complete when the released dependency and notices agree and current focused
|
||
|
|
tests pass. The cross-file inheritance defect is addressed in the next stage;
|
||
|
|
this stage does not claim that new inheritance behavior is fully integrated.
|
||
|
|
|
||
|
|
## Stage 2: Correct direct declaration accounting
|
||
|
|
|
||
|
|
Purpose: allow distinct artifact and family keys to inherit across imported
|
||
|
|
files while preserving existing duplicate-declaration rejection.
|
||
|
|
|
||
|
|
Read `internal/config/pipeline_configkit.go`, particularly
|
||
|
|
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`, and
|
||
|
|
`internal/config/pipeline_configkit_test.go`. Inspect the public ConfigKit
|
||
|
|
`Metadata.History`, `HistoricalPaths`, `Origin`, and `ChangeKind` contracts.
|
||
|
|
|
||
|
|
1. Add package-boundary regression fixtures with a valid parent in one imported
|
||
|
|
file and a child using `extends` in another. Cover ordinary artifacts and
|
||
|
|
artifact families. Give parent and child distinct valid output paths or
|
||
|
|
family patterns, and provide canonical-party context for expanded families.
|
||
|
|
Both keys remain ordinary domain entries; child IDs must stay their own.
|
||
|
|
2. Adjust declaration accounting using retained public metadata. In v0.5.0,
|
||
|
|
original base-input events have `LayerBase` and no origin operation;
|
||
|
|
projected transfers carry `ChangeInheritance`. Count original base
|
||
|
|
declarations, not these transfers or subsequent decoding/resolution events.
|
||
|
|
Consumed structural `extends` paths are not artifact declarations.
|
||
|
|
3. Keep the historical-path check, including original declarations erased by
|
||
|
|
a selected overlay. Do not switch to surviving effective keys only or count
|
||
|
|
all displaced origins as fresh declarations. Reuse a small package-local
|
||
|
|
helper only if it makes the next stage clearer.
|
||
|
|
4. Retain `TestPipelineConfigKitRejectsDuplicateBaseDeclarations`, including
|
||
|
|
disjoint fields supplied to the same key, container removal, and removal of
|
||
|
|
Scriptorium by an overlay. An overlay may still modify an existing entry.
|
||
|
|
Add only any missing regression case needed to exercise the new filter.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config`. The positive cross-file regression
|
||
|
|
should expose the baseline defect before the fix. Assert loaded values and
|
||
|
|
identities, or the duplicate category and relevant sources, without matching an
|
||
|
|
entire diagnostic or ConfigKit's private event ordering.
|
||
|
|
|
||
|
|
Complete when cross-file inheritance loads and expands correctly, and actual
|
||
|
|
duplicates still fail even when the overlay hides them. Do not use the direct
|
||
|
|
declaration filter to remove contributor evidence from inspection.
|
||
|
|
|
||
|
|
## Stage 3: Preserve contributor provenance and family ownership
|
||
|
|
|
||
|
|
Purpose: keep inspection useful when one entry contains values from several
|
||
|
|
files, without confusing its defining file with those contributors.
|
||
|
|
|
||
|
|
Read `internal/config/artifact_catalog.go`,
|
||
|
|
`internal/config/artifact_families.go`, `internal/config/effective_pipeline.go`,
|
||
|
|
and metadata-to-ownership projection in `pipeline_configkit.go`. Inspect the
|
||
|
|
focused catalog, family, and effective-source tests.
|
||
|
|
|
||
|
|
1. Exercise the inherited configurations from Stage 2 through
|
||
|
|
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Check inherited
|
||
|
|
values against their actual parent contributors and child overrides against
|
||
|
|
the child/overlay contributors. Keep historical definition evidence distinct
|
||
|
|
from effective field ownership.
|
||
|
|
2. Preserve `DefinitionSources` aggregation, including inherited contributors.
|
||
|
|
Do not relabel all inherited values as authored in the child's file.
|
||
|
|
3. Correct `artifactFamilySource` where its first inherited field currently
|
||
|
|
selects the parent's file. For an explicitly declared child family, identify
|
||
|
|
its original declaration using retained metadata: use its base defining file
|
||
|
|
when present, or its overlay defining file for an overlay-only family.
|
||
|
|
Overlay edits to a base family do not relocate its base definition.
|
||
|
|
4. Retain the existing fallback for entries without a direct declaration or
|
||
|
|
programmatically constructed configuration. Do not restrict valid enclosing
|
||
|
|
inheritance merely to force every entry into a single-file ownership model.
|
||
|
|
5. Keep logical `SourceID`, artifact keys, family/character/party provenance,
|
||
|
|
existing source roles, and inspection interfaces. Update projections only
|
||
|
|
where inherited evidence is otherwise lost or incorrectly attributed.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config`. Cover an explicitly declared child
|
||
|
|
family inheriting from another file and a selected-overlay contribution. Check
|
||
|
|
meaningful records and source identities, not a complete formatted snapshot.
|
||
|
|
|
||
|
|
Complete when contributor reporting remains truthful and generated members
|
||
|
|
identify their child family definition rather than an arbitrary inherited field.
|
||
|
|
|
||
|
|
## Stage 4: Verify inherited presence, domain resolution, and path bases
|
||
|
|
|
||
|
|
Purpose: prevent Narratio's application defaults or normalization from undoing
|
||
|
|
the library's inherited explicit input.
|
||
|
|
|
||
|
|
Read `pipelineConfigDefaults`, `resolvePipelineConfig`, and
|
||
|
|
`internal/config/load.go`, including `finalizeLoadedPipeline` and
|
||
|
|
`resolveNotariusPaths`. Inspect the current presence/defaulting tests and
|
||
|
|
the relevant domain validators.
|
||
|
|
|
||
|
|
1. Add representative inheritance cases for explicit false, zero, empty,
|
||
|
|
and null input versus genuinely absent input. Include a pointer boolean
|
||
|
|
and an entry-level absence-based default where Narratio consumes metadata.
|
||
|
|
For example, inherited `render_debug: false` can exercise artifact presence;
|
||
|
|
inherited empty Scriptorium timeout can exercise an existing invalid value
|
||
|
|
that must not silently become its default.
|
||
|
|
2. Preserve the existing domain outcome for each chosen field. Valid explicit
|
||
|
|
values retain their value; explicit values already invalid must still fail
|
||
|
|
ordinary validation rather than be refilled. An empty mapping merges under
|
||
|
|
ConfigKit's rules and must not be described as universal container removal.
|
||
|
|
3. Exercise overlay composition before inheritance: modify a parent's field
|
||
|
|
in the selected overlay and confirm the child's inherited result uses that
|
||
|
|
effective value. A child override still wins over its parent.
|
||
|
|
4. Verify a known root-relative field, such as enabled Notarius `config_path`
|
||
|
|
or `working_directory`, when inherited from an imported declaration.
|
||
|
|
Resolve it exactly as the existing field contract does. Do not use passive
|
||
|
|
SourceContext to rebase it to the parent's or child's source directory, or
|
||
|
|
newly normalize other path fields merely to make their behavior uniform.
|
||
|
|
5. Fix any demonstrated Narratio integration defect at its existing defaulting
|
||
|
|
or domain-resolution owner. Use ConfigKit presence and recorded operations;
|
||
|
|
do not recreate structural inheritance or weaken ordinary validation.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config`. Keep coverage representative; generic
|
||
|
|
missing-parent, cycle, resource-context, and expansion-limit matrices belong to
|
||
|
|
ConfigKit. Parents must remain valid Narratio entries, not special templates.
|
||
|
|
|
||
|
|
Complete when inherited explicit input and absent defaults have distinct,
|
||
|
|
correct domain outcomes and existing path bases are unchanged.
|
||
|
|
|
||
|
|
## Stage 5: Verify safe effective projections and inherited credentials
|
||
|
|
|
||
|
|
Purpose: ensure inheritance changes neither semantic comparison nor the
|
||
|
|
existing secret boundary.
|
||
|
|
|
||
|
|
Read `internal/config/effective_pipeline.go`, `effective_digest.go`,
|
||
|
|
`effective_projection.go`, `scriptorium_credentials_test.go`, and the effective
|
||
|
|
projection tests in `load_validate_test.go`. For diff composition, read
|
||
|
|
`internal/app/config_diff.go`. Reuse
|
||
|
|
`TestPipelineOverlayDoesNotRequireUnusedBaseCredentials` and
|
||
|
|
`TestCredentialValuesNeverEnterEffectiveProjectionOrDigest` coverage.
|
||
|
|
|
||
|
|
1. Load two configurations that produce the same effective domain values:
|
||
|
|
one uses inheritance, the other writes the expanded values explicitly.
|
||
|
|
Include ordinary artifacts and representative resolved family members.
|
||
|
|
Verify equal safe effective mappings and digests and no effective diff.
|
||
|
|
Do not compare private provenance as part of semantic equality.
|
||
|
|
2. Add a representative typed credential inheritance case using shared fields
|
||
|
|
of valid Narratio sibling mappings and controlled synthetic environment
|
||
|
|
variables. Verify resolved credentials retain their exact configured names;
|
||
|
|
serialization and inspection expose those identities without values.
|
||
|
|
3. Verify overlay removal/replacement of a credential before inheritance does
|
||
|
|
not resolve the superseded reference. Reuse the existing selected-overlay
|
||
|
|
regression rather than creating a second loader or bootstrap algorithm.
|
||
|
|
4. Check that changing only synthetic secret values leaves semantic projections
|
||
|
|
and digest unchanged. Fix only demonstrated projection defects; preserve
|
||
|
|
the existing safe typed rendering boundary and semantic reuse evidence.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config ./internal/app`. Existing shared adapter
|
||
|
|
credential-forwarding tests remain the owner of subprocess forwarding; do not
|
||
|
|
rewrite adapters or duplicate those tests simply because input can be inherited.
|
||
|
|
|
||
|
|
Complete when resolved values, not source layout or secret bytes, determine
|
||
|
|
effective comparison, and inherited credentials obey the existing safe boundary.
|
||
|
|
|
||
|
|
## Stage 6: Document inheritance and maintain a small example
|
||
|
|
|
||
|
|
Purpose: make the adopted behavior understandable and usable without expanding
|
||
|
|
Narratio's configuration surface.
|
||
|
|
|
||
|
|
Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`,
|
||
|
|
the production/testing bundle, and `TestExamplesLoadAndValidate` in
|
||
|
|
`internal/config/load_validate_test.go`. Follow the documentation policy.
|
||
|
|
|
||
|
|
1. Add native sibling inheritance guidance to the configuration reference.
|
||
|
|
Explain exact sibling lookup, overlay-before-inheritance resolution,
|
||
|
|
explicit presence, ordinary parent validation, distinct child identity,
|
||
|
|
and cross-file declaration/contributor distinctions. Link to the pinned
|
||
|
|
upstream contract for detailed syntax and structural rules.
|
||
|
|
2. Explain the reserved `extends` key throughout ConfigKit inputs, including
|
||
|
|
dynamic artifact IDs and prompt-variable mappings. Operators must rename
|
||
|
|
existing ordinary-data keys with that name; there is no opt-in or automatic
|
||
|
|
conversion. Campaign, session, and party inputs also use ConfigKit.
|
||
|
|
3. Clarify the existing statement that overlays cannot inherit: overlay files
|
||
|
|
cannot inherit or stack, but the selected overlay may supply native sibling
|
||
|
|
directives within its values. Keep imports and overlay selection unchanged.
|
||
|
|
4. Update configuration internals for inheritance before typed decoding,
|
||
|
|
original-declaration counting, contributor projection, and the safe
|
||
|
|
effective boundary. Describe implemented mechanisms, linking to the public
|
||
|
|
reference for their operator-facing meaning.
|
||
|
|
5. In `examples/production-testing/overlays/testing.yml`, add
|
||
|
|
`extends: session_recap` to the existing `testing_notes` artifact. Keep its
|
||
|
|
disabled status and distinct output override. It inherits the imported
|
||
|
|
parent's prompt/input and the parent's testing profile after overlay
|
||
|
|
application. The parent remains an ordinary artifact.
|
||
|
|
6. Update the example guide and extend existing example validation to check
|
||
|
|
those inherited fields. Preserve the bundle's current identities and
|
||
|
|
artifact count; no new example root or template convention is necessary.
|
||
|
|
|
||
|
|
Verify with `go test ./internal/config -run '^TestExamplesLoadAndValidate$'`
|
||
|
|
and `go test ./internal/doccheck`. Review examples for synthetic-only content
|
||
|
|
and validate local links. Keep unimplemented Audita/workspace behavior in its
|
||
|
|
roadmaps. Do not create a release note under an invented Narratio version;
|
||
|
|
reserved-key compatibility impact remains an explicit release-preparation item.
|
||
|
|
|
||
|
|
Complete when canonical documentation and a tested copyable example describe
|
||
|
|
the implemented adoption, without promoting new restrictions to policy.
|
||
|
|
|
||
|
|
## Stage 7: Verify the assembled inspection workflow and close the feature
|
||
|
|
|
||
|
|
Purpose: establish that real command composition consumes the integrated
|
||
|
|
configuration correctly and finish the upgrade as a reviewable baseline.
|
||
|
|
|
||
|
|
Read `internal/app/config_commands_test.go`, `config_artifacts_test.go`,
|
||
|
|
and existing read-only inspection workflow coverage. Reuse the preceding
|
||
|
|
package coverage rather than repeating its entire matrix at the CLI boundary.
|
||
|
|
|
||
|
|
1. Add or extend a representative command-level temporary imported bundle with
|
||
|
|
inheritance. Exercise validation, effective show, source reporting, artifact
|
||
|
|
catalog, and diff through existing command entry points. Use a campaign/party
|
||
|
|
fixture for family inspection, and paired overlays with equivalent inherited
|
||
|
|
and explicitly expanded values when testing command-level diff equality.
|
||
|
|
2. Check semantic output: resolved child values, expected contributor/defining
|
||
|
|
sources, logical artifact identities, and no secret values. Keep inspection
|
||
|
|
read-only with respect to session/runtime state, as existing tests establish.
|
||
|
|
Do not invoke downstream applications or add CLI modes or columns.
|
||
|
|
3. Review the combined diff against `config.md` and this plan. Confirm that
|
||
|
|
ConfigKit v0.5.0 is selected, attribution links use the reviewed revision,
|
||
|
|
no optional loading feature was adopted, and no Audita/workspace change or
|
||
|
|
compatibility shim slipped into scope.
|
||
|
|
4. Run `go test ./...`, `go test -race ./...`, `go vet ./...`,
|
||
|
|
`go build ./...`, `go mod tidy -diff`, and `git diff --check` against the
|
||
|
|
final source. These reuse existing repository checks, not new release gates.
|
||
|
|
The full suite includes example and documentation-link validation; focused
|
||
|
|
checks need not be repeated solely for this stage if unchanged.
|
||
|
|
5. Commit the completed unit and report the dependency revision, checks,
|
||
|
|
compatibility impact, and any unfinished work. Leave the pending Audita and
|
||
|
|
workspace plans and Proposed ADRs intact. Retire completed planning files
|
||
|
|
only during separately requested cleanup/release preparation, repairing links.
|
||
|
|
|
||
|
|
Complete when the feature roadmap's completion criteria are evidenced by the
|
||
|
|
released dependency, integrated behavior, maintained documentation/examples,
|
||
|
|
and passing final checks. The next implementation scope is Audita; its concrete
|
||
|
|
plan is prepared separately. Release version selection and publication are
|
||
|
|
outside this implementation pass.
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
|
||
|
|
None required for this adoption. Existing decisions select native inheritance,
|
||
|
|
current loading/path/credential semantics, and ConfigKit before Audita before
|
||
|
|
workspace work. Eventual release preparation must account for the reserved-key
|
||
|
|
compatibility impact under the release policy; no version is selected here.
|