366 lines
22 KiB
Markdown
366 lines
22 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.
|
|
|
|
ConfigKit owns source assembly and native provenance. Narratio validates the
|
|
effective domain configuration and exposes the library's metadata to operators.
|
|
This revision replaces the earlier plan to repair declaration-history counting
|
|
with removal of that additional acceptance rule. It retains supported callbacks,
|
|
presence-sensitive defaults, party ordering, and provenance inspection.
|
|
|
|
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.
|
|
- Trust ConfigKit's structural acceptance rules. Remove Narratio's
|
|
one-base-file-per-entry check rather than making it inheritance-aware. Validate
|
|
resulting domain values; source history is diagnostic evidence, not another
|
|
acceptance gate. Parent entries that survive composition remain ordinary
|
|
entries subject to applicable domain rules.
|
|
- Use native presence and provenance APIs for defaults and operator inspection.
|
|
Keep supported callbacks and party ordering. Do not impose post-`Load` callback
|
|
relocation, relaxed empty/null semantics, or retirement of `config sources`.
|
|
- 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 reconstruct provenance or validate old input.
|
|
- 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.
|
|
- Update affected canonical documentation with each implemented behavior change.
|
|
In particular, Stage 2 updates the removed authoring restrictions and Stage 3
|
|
updates changed inspection meanings. Stage 6 consolidates the policy review,
|
|
inheritance guidance, and example; it is not a reason to leave earlier
|
|
completed commits describing obsolete behavior.
|
|
- For documentation updates, state the policy affirmatively using concise,
|
|
factual language. Avoid negative parallelism.
|
|
|
|
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 [x]
|
|
|
|
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: Remove source-authoring acceptance gates [x]
|
|
|
|
Purpose: accept structurally composed configuration from ConfigKit and reject
|
|
only invalid effective Narratio domain configuration.
|
|
|
|
Read `internal/config/pipeline_configkit.go`, particularly
|
|
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`,
|
|
`pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in
|
|
`internal/config/artifact_families.go` and `artifact_families_test.go`.
|
|
|
|
1. Delete `rejectDuplicateBaseDefinitions` and its invocation. Do not replace
|
|
it with filtering of inheritance events, direct-declaration counting, or
|
|
another source-history validator.
|
|
2. Replace `TestPipelineConfigKitRejectsDuplicateBaseDeclarations` with behavior
|
|
coverage showing that disjoint contributions to one artifact/family compose
|
|
successfully when the resulting domain entry is valid. Check selected-overlay
|
|
replacement/removal without Narratio rejecting superseded declarations.
|
|
3. Add cross-file artifact and family inheritance regressions. Supply valid
|
|
surviving parent and child entries with distinct output destinations, and
|
|
campaign/party context for family expansion. Verify child identities and
|
|
effective fields; the inheritance regression must fail on the old check.
|
|
4. Remove the `publishDeclared` gate in `expandFamilyPublishRules`, its metadata
|
|
population, and state retained only for that gate. Validate family publication
|
|
against the effective `Publish` value, whether authored or supplied by defaults.
|
|
Preserve the missing-effective-publish check, ordinary enablement behavior,
|
|
destination validation, and conflicts between effective publish rules.
|
|
Update the test that currently fabricates an explicit-declaration flag.
|
|
5. Retain effective-domain rejection, including invalid artifacts, unresolved
|
|
dependencies, and destination collisions under current rules. Reuse existing
|
|
tests where adequate. Retain a representative structural-conflict check at
|
|
the loader boundary; ConfigKit owns the full conflict/precedence matrix.
|
|
|
|
Verify with `go test ./internal/config`. Assert effective outcomes and safe
|
|
error categories, not entire diagnostic text or private metadata event order.
|
|
Do not run a separate base-only load to validate overwritten input.
|
|
|
|
Complete when valid cross-file composition/inheritance succeeds and invalid
|
|
effective configuration still fails before execution, without authored-source
|
|
acceptance gates. Keep native metadata available for the next stage.
|
|
|
|
## Stage 3: Simplify provenance inspection around native APIs [x]
|
|
|
|
Purpose: preserve useful operator inspection without a parallel provenance
|
|
system or a unique-defining-file contract for composite entries.
|
|
|
|
Read `internal/config/artifact_catalog.go`, `artifact_families.go`,
|
|
`effective_pipeline.go`, `effective_digest.go`, and the metadata projection in
|
|
`pipeline_configkit.go`. Inspect `internal/app/config_commands_test.go`,
|
|
`config_artifacts_test.go`, and ConfigKit's public metadata contracts.
|
|
|
|
1. Keep `config sources` and provenance-bearing `config artifacts` output.
|
|
Use public ConfigKit sources, effective origins, history, and explanations
|
|
for the information they own. Keep presence queries and recorded callbacks
|
|
where needed; retaining returned metadata is not duplicating its implementation.
|
|
2. Review existing helper/state layers for duplicated tracking. Remove redundant
|
|
cached field-ownership reconstruction where the same result is available
|
|
directly from retained metadata. Keep a small projection where needed for
|
|
Narratio's generated family/character/party context and output formatting.
|
|
Do not add a provenance service, custom ancestry graph, or second source parse.
|
|
3. Exercise Stage 2's inherited and multi-file entries through
|
|
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Report actual
|
|
contributors and child overrides. Keep historical definition evidence
|
|
distinguishable from effective field origins as exposed by ConfigKit.
|
|
4. Replace `artifactFamilySource`'s arbitrary first-contributor ownership with
|
|
native source/origin evidence. Do not infer a unique base defining file or
|
|
implement a new declaration-accounting algorithm. Composite origins may have
|
|
several sources; preserve them using existing repeated source records and
|
|
comma-separated catalog source lists. Adjust the runtime-only representation
|
|
minimally where a single-source field cannot carry that evidence.
|
|
5. Preserve logical artifact IDs, family/character identities, party provenance,
|
|
inspection command names, and read-only behavior. Retain existing headers
|
|
where their meanings remain accurate; explain that family source evidence may
|
|
be composite instead of promising a unique defining file. Do not change
|
|
native-metadata-based party ordering merely to avoid library APIs.
|
|
|
|
Verify with `go test ./internal/config ./internal/app`. Cover a child family
|
|
inheriting across files, an entry composed from disjoint files, and an overlay
|
|
override. Check meaningful source records, logical identities, and absence of
|
|
secret values rather than full formatted snapshots or upstream event ordering.
|
|
|
|
Complete when native provenance remains useful and truthful, redundant tracking
|
|
is removed where practical, and no acceptance rule depends on contributor count
|
|
or an inferred defining file. Application derivation context remains available.
|
|
|
|
## 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;
|
|
retain supported defaults/resolver/validator callbacks. There is no required
|
|
move to post-`Load` functions. Do not recreate structural inheritance, inspect
|
|
old input to add acceptance rules, or relax empty/null semantics to avoid
|
|
using the library's presence API.
|
|
|
|
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: Align policy, document inheritance, and maintain an 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`,
|
|
`docs/policy/architecture.md`, the production/testing bundle, and
|
|
`TestExamplesLoadAndValidate` in
|
|
`internal/config/load_validate_test.go`. Follow the documentation policy.
|
|
|
|
1. Revise only the project-specific Configuration section of the architecture
|
|
policy to record the implemented boundary: ConfigKit owns loading, assembly,
|
|
inheritance, presence, secrets, and provenance; Narratio owns domain meaning
|
|
and fail-fast effective validation. Permit native metadata inspection and
|
|
supported callbacks. Align the ambiguous empty-value statement with existing
|
|
explicit-presence defaults, not a new blank/null policy. Leave general
|
|
upstream agent, testing, documentation, and OSS policy wording unchanged.
|
|
2. 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 native contributor inspection. Remove the one-base-file restriction and
|
|
describe acceptance of ConfigKit-composed entries. Update family-publish
|
|
guidance for effective configuration rather than explicit authoring. Link to
|
|
the pinned upstream contract for detailed syntax and structural rules.
|
|
3. 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.
|
|
4. 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.
|
|
5. Update configuration internals for inheritance before typed decoding,
|
|
removal of authoring gates, thin native contributor projection, and the safe
|
|
effective boundary. Describe implemented mechanisms, linking to the public
|
|
reference for their operator-facing meaning. Update `docs/cli.md` where source
|
|
output now reports composite evidence rather than a unique defining file.
|
|
6. 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.
|
|
7. 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, native contributor/origin
|
|
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 introduce new inspection modes.
|
|
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,
|
|
authoring-history acceptance checks were removed, native inspection and
|
|
presence semantics remain, and policy reflects that boundary. Confirm no
|
|
optional loading feature, 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,
|
|
native metadata inspection and callbacks, effective-domain validation instead
|
|
of authoring-history gates, current path/credential/presence semantics, and
|
|
ConfigKit before Audita before workspace work. Eventual release preparation must
|
|
account for the reserved-key compatibility impact and inspection representation
|
|
changes under the release policy; no version is selected here.
|