Retire the completed ConfigKit upgrade plans
This commit is contained in:
@@ -1,298 +0,0 @@
|
||||
# Adopt Current ConfigKit Configuration Semantics
|
||||
|
||||
## Purpose
|
||||
|
||||
Adopt `go.maximumdirect.net/configkit` v1.2.0 and its native consumer workflow.
|
||||
The objective is consistent configuration semantics across ConfigKit-consuming
|
||||
applications. Existing Notarius composition behavior is a migration baseline,
|
||||
not a compatibility requirement to reproduce through adapters.
|
||||
|
||||
This work set retains PromptKit v0.12.0 and go-yaml v4.0.0-rc.6. ConfigKit
|
||||
v1.2.1 and stable go-yaml v4.0.0 belong to the subsequent PromptKit upgrade.
|
||||
|
||||
[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the
|
||||
boundary: ConfigKit delivers the final resolved application document; Notarius
|
||||
supplies application schema, defaults, normalization, validation, and subsequent
|
||||
pipeline resolution. This roadmap defines the target and required work. The
|
||||
[implementation plan](implementation.md) owns sequencing and stage verification.
|
||||
Release publication is separate work.
|
||||
|
||||
## Reviewed Baseline And Sources
|
||||
|
||||
Reviewed on 2026-11-17 against Notarius `b9899ea`:
|
||||
|
||||
- ConfigKit v0.5.0 under `gitea.maximumdirect.net/eric/ConfigKit`;
|
||||
- PromptKit v0.12.0, which consumes that same old ConfigKit package;
|
||||
- Go 1.25.5 and go-yaml v4.0.0-rc.6;
|
||||
- Notarius configuration version 5, imports, overlays, sibling inheritance,
|
||||
declaration-relative application paths, and effective/explanation CLI reports.
|
||||
|
||||
The target v1.2.0 tag in `../ConfigKit` identifies source commit
|
||||
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. Review references:
|
||||
|
||||
- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/consumers/README.md)
|
||||
- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
|
||||
- [Release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/releases/)
|
||||
|
||||
All intervening release notes were read in the local checkout. The important
|
||||
changes are:
|
||||
|
||||
| Releases | Relevance to Notarius |
|
||||
| --- | --- |
|
||||
| v0.6.0 | Loading/inspection optimizations; Go minimum becomes 1.26.0. No promised application-wide speedup. |
|
||||
| v0.7.0–v0.7.1 | Frozen effective-configuration diffs; maintainer tooling update. |
|
||||
| v0.8.0 | Input destinations, sequence-item placement, source-version checks, and identified sequences. |
|
||||
| v0.9.0 | Expanded imports; imports optional by default; author-declared replace/append/upsert; identified-record inheritance; CLI assignments move after inheritance and decoding. |
|
||||
| v0.10.0–v0.10.2 | Explicit configuration discovery; broader absent-main lifecycle; loading, ownership, acquisition, and history fixes. |
|
||||
| v1.0.0 | New module path, source-root `config` controls, public API cleanup, source lookup, and Go 1.27.0 minimum. |
|
||||
| v1.1.0 | Field-level normalization inside lists; identity-aware provenance/history across record movement. |
|
||||
| v1.2.0 | Main-relative companion inputs and layered overlay context selection. |
|
||||
| v1.2.1 (reviewed, deferred) | Stable go-yaml v4.0.0 and loader-plugin adaptation; adopted with the subsequent PromptKit upgrade. |
|
||||
|
||||
### Current Integration Areas
|
||||
|
||||
`internal/core/config/load.go` supplies ConfigKit's definition and callbacks.
|
||||
`loaded_config.go` privately retains its inspection result and publishes a
|
||||
detached runtime value. `document_paths.go`, `pipeline_document.go`, and
|
||||
`document_normalizer.go` implement application normalization and source tracking.
|
||||
The normalizer currently records whole-list coverage even for leaf edits.
|
||||
|
||||
`internal/cli/configkit_load.go` and `run.go` own selection and diagnostics.
|
||||
`discoverConfigPath` manually probes files before `config.Load` calls ConfigKit.
|
||||
The complete example imports its pipeline through root `configkit`. Current
|
||||
documentation describes unconditionally replacing whole step lists.
|
||||
|
||||
ConfigKit types also appear inside the PromptKit adapter's native source and
|
||||
inspection APIs. That is a distinct integration boundary with the dependency
|
||||
constraint below; a repository-wide import replacement would be incorrect.
|
||||
|
||||
## Target End State
|
||||
|
||||
### Native Loading And Ownership
|
||||
|
||||
Use the new public package and the ordinary `Load` workflow for the application
|
||||
configuration. Defaults, `Resolve`, `Validate`, `VersionRule`, and sensitivity
|
||||
classification remain supported application extension points. The handoff
|
||||
contains fully composed, decoded, normalized, and validated application values.
|
||||
Runtime conversion and catalog-dependent pipeline preparation retain their
|
||||
application ownership.
|
||||
|
||||
ConfigKit owns import acquisition, ordering, inheritance, collection operations,
|
||||
CLI assignment semantics, limits, source evidence, and frozen inspection. Pass
|
||||
its results and structured failures through the established adapter boundary.
|
||||
Application validation checks the resulting domain configuration; it does not
|
||||
audit superseded contributions or replay structural directives.
|
||||
|
||||
Keep configuration `version: 5`: its typed application shape is unchanged.
|
||||
Explain the deliberate ConfigKit syntax/semantic migration in operator guidance
|
||||
and the eventual minor-release note. Existing files require migration rather
|
||||
than a compatibility pre-parser or legacy control aliases.
|
||||
|
||||
### Source Controls, Imports, And Composition
|
||||
|
||||
Use source-root `config` controls in Notarius configuration inputs. Update real
|
||||
control blocks and stored declaration pointers, including imported files,
|
||||
overlays, mapping fixtures, and examples. Nested application data named `config`
|
||||
retains native treatment. Former `configkit`/`_configkit` keys are ordinary data;
|
||||
ordinary typed validation governs them. No custom legacy-control scanner is
|
||||
needed.
|
||||
|
||||
This control migration applies to Notarius's application loader. PromptKit
|
||||
operator files and adapter fixtures follow the version of PromptKit that reads
|
||||
them; retain their old control spelling while that separate engine remains old.
|
||||
|
||||
Enable ConfigKit imports and accept its native path/list, directory, glob,
|
||||
destination, placement, exclusion, recursion, hidden-file, symlink, and
|
||||
requiredness rules. Leave `ImportDefaults` unspecified unless an application
|
||||
choice is explicitly approved. In particular, do not restore former implicit
|
||||
requiredness or impose a YAML-only directory filter globally. Required deployed
|
||||
fragments, such as the maintained complete pipeline import, should say
|
||||
`required: true` in their declaration so an incomplete installation fails there.
|
||||
Optional imports remain genuinely optional.
|
||||
Use the native main-only source-version default; fragments do not acquire a new
|
||||
mandatory version declaration as a side effect of this upgrade.
|
||||
|
||||
Expose native identified sequence operations and inheritance through the source
|
||||
format. Without identity, lists retain native peer-conflict/whole-replacement
|
||||
behavior. Identified lists support strict peer composition and native
|
||||
replace/append/upsert across tiers. Upsert replaces a complete matching record,
|
||||
retaining its position; it is not a recursive merge of that record. Clearing an
|
||||
append/upsert collection requires explicit replacement with an empty list.
|
||||
Dependency-ready assembly order, not a Notarius sorting or append pass, controls
|
||||
composition. Final Notarius checks still validate stage order, supported modules,
|
||||
reference dependencies, and unique application identifiers.
|
||||
|
||||
Register `id` for `/pipelines/<any-mapping-key>/steps` through
|
||||
`SequenceIdentityMatching`. Step IDs already carry application meaning and
|
||||
uniqueness requirements. Native identity permits independently imported steps
|
||||
and supplies the ordinary upsert default for overlays and inheritance. Authors
|
||||
can explicitly select replacement or append. Other identified collections
|
||||
remain available through author declarations; no broad automatic `id` inference
|
||||
or universal registration is required. Demonstrate a composed step list and a
|
||||
derived pipeline using native controls in maintained examples or small canonical
|
||||
snippets, with behavioral coverage.
|
||||
|
||||
CLI overrides apply after inheritance and typed decoding, before application
|
||||
resolution. Preserve explicit zero/false/empty values. Structural errors cannot
|
||||
be repaired by CLI assignments; document this instead of rebuilding the former
|
||||
override order. Notarius's binding-profile and validation-policy rules remain
|
||||
domain semantics applied to the final configuration.
|
||||
|
||||
### Native Source Selection And Resources
|
||||
|
||||
Replace manual acquisition/probing with ConfigKit source descriptions. Explicit
|
||||
`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive
|
||||
`File` sources: a missing selected file fails instead of searching elsewhere.
|
||||
For default discovery use `SearchConfig` with `Searches` composing these native
|
||||
presets in order:
|
||||
|
||||
1. `WorkingDirectory()`;
|
||||
2. `UserConfigDirectory()`; and
|
||||
3. `UnixSystemDirectories()`.
|
||||
|
||||
Together with the explicit selections above, precedence is `--config`, then
|
||||
`NOTARIUS_CONFIG`, then working-directory, user-configuration, and system searches.
|
||||
Retain each preset's native filename groups and ordering. In particular, the
|
||||
working-directory preset selects `notarius.yml`, then `notarius.yaml`, rather
|
||||
than generic `config.yml`; user and system presets retain their native named
|
||||
and generic filename groups in their applicable directories. Use the presets
|
||||
directly rather than maintaining a parallel filename list or overriding their
|
||||
filename options. The separate `HomeDirectory()` preset is not enabled.
|
||||
|
||||
Discovery selects one main file; it does not merge files from all search
|
||||
locations. Missing candidates advance the search under ConfigKit's rules. Access
|
||||
errors and failures loading a selected file are terminal rather than reasons to
|
||||
try a lower-priority configuration. A reached directory-resolution failure also
|
||||
remains terminal; later search directories need not be resolved once an earlier
|
||||
candidate is selected. Document working-directory-dependent selection and
|
||||
recommend explicit `--config` for services and subprocess callers that want a
|
||||
fixed selection.
|
||||
|
||||
Use a required search for commands that require a configuration file, preserving
|
||||
their need for a selected configuration. This does not impose requiredness on
|
||||
all imports or on separate defaults-only programmatic loads.
|
||||
|
||||
Report the actual selected main file using retained source information; update
|
||||
load/error plumbing rather than making a second discovery pass. Construction of
|
||||
search descriptions remains side-effect-free, and acquisition errors follow
|
||||
ConfigKit's native selected-file behavior.
|
||||
|
||||
Retain the deliberately selected application path policy: file-authored values
|
||||
use their declaring file, CLI paths use the invocation directory, and relative
|
||||
application defaults use the canonical main file. Use `EntryInfo`, source records,
|
||||
and public resource contexts where appropriate. Native destinations and source
|
||||
coordinates are distinct: a mounted or inherited value keeps its source base.
|
||||
No new target-existence, confinement, symlink, or permission policy is added to
|
||||
application resource paths. ConfigKit's own input-root rules remain upstream.
|
||||
|
||||
Ordinary `Load` is sufficient for current application composition. `LoadLayered`,
|
||||
`MainRelative`, and overlay fallbacks are available when actual bundled/companion
|
||||
inputs need them; the upgrade does not require an artificial extra input layer.
|
||||
|
||||
### Lean Application Resolution And Inspection
|
||||
|
||||
Replace `InputInfo` with `EntryInfo`, `Definition.Secret` with `Sensitive`,
|
||||
generic `Record` calls with the corresponding named recording methods, and
|
||||
`LayerBase`/`"base"` with `LayerMain`/`"main"` where used. Audit all affected
|
||||
symbols and diagnostic strings against the v1 migration table. Use assignment-
|
||||
and-record helpers when appropriate; named recording methods alone do not mutate
|
||||
the application value.
|
||||
|
||||
Use v1.1 field-level recording for list leaf normalization. Remove the old
|
||||
blanket whole-sequence coverage wrapper where its only purpose was satisfying
|
||||
the old audit. Record actual structural mutations at their proper scope. Resolve
|
||||
source-relative values before moving records; fixed entry positions, final
|
||||
positions, historical evidence, and effective origins serve different purposes.
|
||||
Keep map-key relocation bookkeeping only where actual application identifier
|
||||
normalization still needs it. Do not add an independent history-replay engine.
|
||||
|
||||
Effective/explanation commands delegate to ConfigKit's captured inspection,
|
||||
retaining redaction, presence, source history, and detached ownership. Source
|
||||
lookup APIs support useful diagnostics, including empty import selections when
|
||||
needed, without turning ordinary optional absence into warnings. ConfigKit's
|
||||
`Diff` is available for a later operator-facing comparison command; a new CLI
|
||||
diff or secrets-management workflow is not required for this adoption.
|
||||
|
||||
## Dependency And Toolchain Boundary
|
||||
|
||||
The target is ConfigKit v1.2.0, go-yaml v4.0.0-rc.6, and a Go consumer minimum
|
||||
of 1.27.0. Update the selected release-validation toolchain, setup guidance, and
|
||||
actual configured build/CI environments consistently. Minimum and validation
|
||||
patch remain separate choices. Include Go and configuration migration impact in
|
||||
the eventual release note; patch releases cannot raise the Go minimum.
|
||||
|
||||
PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`,
|
||||
its source helpers, and inspection. The approved intermediate architecture
|
||||
retains old-path ConfigKit v0.5.0 for that dependency while ordinary Notarius
|
||||
configuration uses new-path ConfigKit v1.2.0. Keep each package's types inside
|
||||
its owning integration boundary. Prefer neutral scalar/domain handoffs over
|
||||
translating dependency-owned graphs. Maintain the old PromptKit format for its
|
||||
operator files and fixtures during this work set.
|
||||
|
||||
The selected intermediate versions share YAML rc.6. A direct v1.2.1 upgrade
|
||||
would introduce a shared-dependency incompatibility:
|
||||
|
||||
- ConfigKit v1.2.1 requires stable go-yaml v4.0.0.
|
||||
- Old-path ConfigKit v0.5.0 imports `go.yaml.in/yaml/v4/plugin/limit`.
|
||||
- Stable go-yaml contains `plugin/loaderlimits` and no `plugin/limit`.
|
||||
- Go selects one version of this shared YAML module, despite ConfigKit itself
|
||||
having two distinct module paths.
|
||||
|
||||
Targeting v1.2.0 avoids that specific package-removal conflict using released
|
||||
dependencies, without maintaining an upstream compatibility patch. Verify the
|
||||
mixed dependency graph and native build early in implementation; no trial build
|
||||
has yet established full compatibility. This work set is complete at v1.2.0
|
||||
when its native semantics and integration pass acceptance, independently of the
|
||||
later PromptKit upgrade.
|
||||
|
||||
## Required Repository Work And Acceptance
|
||||
|
||||
- Migrate application-side dependency imports, APIs, diagnostics, source
|
||||
declarations, inspection, and discovery. Verify coexistence of new-path
|
||||
ConfigKit v1.2.0, old-path v0.5.0, PromptKit v0.12.0, and YAML rc.6 without
|
||||
dependency forks or replacements. Native builds must pass at completion.
|
||||
- Update real-file loading, imports, overlays, inheritance, CLI assignment,
|
||||
path-origin, failure, and ownership tests under `internal/core/config` and
|
||||
`internal/cli`. Add representative collection composition and step-reference
|
||||
normalization cases, including imports in distinct directories and leaf
|
||||
histories after list composition. Test native semantics, not the old behavior.
|
||||
- Verify discovery precedence from explicit CLI and environment selections
|
||||
through working-directory, user, and system presets. Cover native filename
|
||||
ordering, missing-candidate continuation, required-search exhaustion, and
|
||||
terminal selected-file failures without adding a separate discovery engine.
|
||||
- Retain two top-level configuration examples. Migrate the complete example's
|
||||
required import and demonstrate useful native composition without adding a
|
||||
second application merger or an unnecessary example framework.
|
||||
- Revise `docs/config.md`, `docs/cli.md`, `docs/internal/configuration.md`, and
|
||||
affected operations/subprocess guidance for syntax, search, imports, collections,
|
||||
CLI ordering, origins, and inspection. Update README/toolchain/release guidance
|
||||
and affected dependency integration references. Preserve accepted ADR history;
|
||||
ADR-0020 already supplies the durable ownership rationale.
|
||||
- Update `docs/oss/attribution.md` from actual selected module revisions and
|
||||
notices, including both selected ConfigKit module identities, retained YAML rc.6,
|
||||
and newly selected transitive dependencies. Preserve the application grant.
|
||||
Upstream ReleaseKit is maintainer tooling; adopting it as Notarius release
|
||||
machinery or adding its gates is outside this feature.
|
||||
- Verify focused configuration/CLI/LLM tests, full offline tests, vet, a native
|
||||
build, maintained examples and report commands without provider calls, tidy
|
||||
consistency, selected module identities, and affected links. No production
|
||||
inference, fixed performance improvement, new release gate, or broader
|
||||
filesystem/security guarantee is part of acceptance.
|
||||
|
||||
Completion means current native configuration semantics are usable and documented
|
||||
on a coherent dependency graph, with final domain validation and no unresolved
|
||||
directives at runtime. The old ConfigKit 0.5 roadmap is replaced by this feature
|
||||
scope; unrelated completed plans and review findings remain separate records.
|
||||
|
||||
## Deferred To The PromptKit Upgrade
|
||||
|
||||
The next work set upgrades PromptKit together with ConfigKit v1.2.1 and stable
|
||||
go-yaml v4.0.0. Its roadmap will cover PromptKit's module/API and source-format
|
||||
migration, replace the temporary old-path ConfigKit integration, and remove old
|
||||
dependencies when no longer used. It will also update the relevant tests,
|
||||
inspection/checkpoint integration, documentation, and attribution for the final
|
||||
selected graph. That later work does not gate completion of this v1.2.0 scope.
|
||||
|
||||
The dependency approach, ordered native discovery presets, and application step
|
||||
identity registration are approved decisions. No significant open decisions
|
||||
remain for this feature roadmap.
|
||||
@@ -1,524 +0,0 @@
|
||||
# ConfigKit 1.2.0 Implementation Plan
|
||||
|
||||
## Scope And Working Rules
|
||||
|
||||
Implement [the feature roadmap](configkit.md), whose approved choices govern
|
||||
this plan. The baseline is `2c8b631`: old-path ConfigKit v0.5.0, PromptKit
|
||||
v0.12.0, Go 1.25.5, and YAML v4.0.0-rc.6. Target new-path ConfigKit v1.2.0 at
|
||||
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`, Go minimum 1.27.0, and the same
|
||||
PromptKit/YAML versions. Use `git show v1.2.0:<path>` in `../ConfigKit` for pinned
|
||||
guidance; its moving checkout may contain v1.2.1's incompatible YAML changes.
|
||||
|
||||
During planning, the configuration, CLI, and LLM suites passed with the existing
|
||||
Go 1.25.5 graph. No upgraded-graph trial was performed; these baseline results
|
||||
do not establish compatibility with the target dependencies.
|
||||
|
||||
Each numbered stage is one prompt for Luna, executed in order in a single
|
||||
end-to-end sprint. Intermediate revisions may fail compilation or tests. Record
|
||||
those failures and continue with the owning stage; avoid transitional parsers,
|
||||
type-translation layers, or duplicate machinery just to keep intermediate
|
||||
commits green. Completion requires all stages and the final acceptance checks.
|
||||
|
||||
For every stage:
|
||||
|
||||
- Read `docs/development.md`, `docs/policy/agents.md`, the feature roadmap, and
|
||||
applicable architecture/testing/documentation/OSS/release policies. Reuse
|
||||
unchanged context. Prefer the code graph for discovery.
|
||||
- Keep ConfigKit responsible for source mechanics and final inspection, per
|
||||
ADR-0020. Notarius owns application rules and runtime pipeline resolution.
|
||||
- Preserve configuration version 5, artifact/subprocess contracts, LLM behavior,
|
||||
cache permissions, and existing retry/scheduling policy. Native composition,
|
||||
discovery, CLI ordering, and control syntax intentionally change.
|
||||
- Use `GOWORK=off`. Keep dependencies released and selected through ordinary Go
|
||||
module resolution. ConfigKit v1.2.1, stable YAML, PromptKit migration, release
|
||||
publication, and unrelated remediation findings are outside this sprint.
|
||||
- Test real loading with temporary files. Keep tests offline and credential-free;
|
||||
inject only external LLM/HTTP boundaries. Reuse coverage instead of mirroring
|
||||
the entire upstream suite or snapshotting incidental diagnostics.
|
||||
- Review the diff and commit nonempty units under agent policy. Record actual
|
||||
validation and deferred checks. No empty commits, pushing, tagging, roadmap
|
||||
retirement, or changes to accepted ADR bodies.
|
||||
|
||||
## Settled Implementation Details
|
||||
|
||||
### Package Identity And Loading Handoff
|
||||
|
||||
Application configuration and CLI configuration overrides/diagnostics use
|
||||
`go.maximumdirect.net/configkit` v1.2.0. PromptKit v0.12.0's source helpers and
|
||||
inspection continue to use `gitea.maximumdirect.net/eric/ConfigKit` v0.5.0 inside
|
||||
the LLM adapter and direct integration fixtures. These named types are distinct.
|
||||
Do not globally replace imports or pass a new-package path/source to old PromptKit.
|
||||
|
||||
Keep `config.Load(path, options)` as an exclusive file convenience. Add
|
||||
`config.LoadSource(source configkit.Source, options LoadOptions)` for a
|
||||
production source supplied by the composition boundary, with imports enabled.
|
||||
Both reach the same definition/callback/load path. Private byte/reader test
|
||||
helpers may retain their existing explicit import choice. This configuration
|
||||
package is the explicit ConfigKit integration boundary; upstream values stay
|
||||
out of runtime pipeline/module contracts.
|
||||
|
||||
The CLI selects a source without filesystem probes:
|
||||
|
||||
1. Trim a nonblank `--config` value and use `File` exclusively.
|
||||
2. Otherwise use a nonblank `NOTARIUS_CONFIG` via the existing injected
|
||||
`LookupEnv`, selecting `File` exclusively.
|
||||
3. Otherwise construct `SearchConfig("notarius", Searches(WorkingDirectory(),
|
||||
UserConfigDirectory(), UnixSystemDirectories()), SearchOptions{Required:true})`.
|
||||
|
||||
Pass that source into `LoadSource` exactly once. Add a neutral
|
||||
`LoadedConfig.MainSourcePath()` accessor based on retained sources: select the
|
||||
non-imported main file (`LayerMain`, `SourceKindFile`, nil `ImportedFrom`). Return
|
||||
its recorded path, or empty for a non-file private/programmatic load. Do not
|
||||
infer the main file from source IDs, a particular field's surviving origin, or
|
||||
another filesystem search. Keep `loadConfigKit`'s selected-path string return
|
||||
and populate it from this accessor. Debug/invocation provenance then describes
|
||||
the actual selected main. Its existing flag/discovered category need not expand.
|
||||
|
||||
Native search filename groups, missing-candidate behavior, selected-file failure,
|
||||
and directory-helper timing remain upstream behavior. WorkingDirectory searches
|
||||
`notarius.yml`, then `notarius.yaml`; generic filenames belong only to the
|
||||
presets that include them. HomeDirectory is not added. Files are selected, not
|
||||
automatically layered. NoSource remains a separate explicit programmatic choice.
|
||||
|
||||
### Native Collections And Application Resolution
|
||||
|
||||
Register precisely this identity on the application definition:
|
||||
|
||||
```go
|
||||
configkit.SequenceIdentityMatching(configkit.SequenceSelector{
|
||||
configkit.SequenceLiteralKey("pipelines"),
|
||||
configkit.SequenceAnyMappingKey(),
|
||||
configkit.SequenceLiteralKey("steps"),
|
||||
}, "id")
|
||||
```
|
||||
|
||||
Use native upsert by default for those identified lists. A matching step is
|
||||
replaced as a whole, not field-merged; order and clearing follow native rules.
|
||||
Source authors may select replace/append explicitly and declare identities for
|
||||
other lists. Do not register validator chains or infer identities elsewhere.
|
||||
Application validation still checks actual domain constraints after resolution.
|
||||
|
||||
Leave import defaults and source-version mode at native defaults. Maintained
|
||||
required fragments say `required: true`; other absent imports remain optional.
|
||||
Keep version 5 main validation without requiring version headers on every fragment.
|
||||
Do not impose global filename filtering, hidden-file, symlink, or recursion rules.
|
||||
CLI assignments occur after typed decode/inheritance and before Resolve.
|
||||
|
||||
Replace blanket list recording with leaf records for actual leaf edits. Keep
|
||||
whole-container records for actual map-key or list structure changes. Normalize
|
||||
paths and nested reference keys while records still have entry order; use
|
||||
EntryInfo to follow the source of the original scalar, then record the final
|
||||
field. ConfigKit composition has already assembled step positions before Resolve.
|
||||
Step-ID trimming can change correspondence: it does not justify an extra custom
|
||||
identity matcher or a promise that every transformed record retains a file origin.
|
||||
Test changed identities with native auditing and record an ancestor when needed.
|
||||
|
||||
Map-key normalization remains application behavior. Retain original-path tracking
|
||||
where a renamed pipeline/lane/reference key requires it; reduce redundant state
|
||||
only after the updated origin tests prove it unnecessary. Preserve file-relative,
|
||||
CLI-invocation-relative, default-main-relative, absolute, and empty-cache path
|
||||
semantics. No new resource-existence or access policy is introduced.
|
||||
|
||||
## Stage 1 — Select The Mixed Dependency Graph And Toolchain
|
||||
|
||||
**Complete.** Go 1.27.0 was verified using the locally installed toolchain;
|
||||
both ConfigKit packages build with YAML v4.0.0-rc.6, and the existing config,
|
||||
CLI, and LLM packages compile with the selected graph. Application API migration
|
||||
and full behavioral checks remain in their respective stages.
|
||||
|
||||
Goal: establish the approved build inputs without migrating PromptKit.
|
||||
|
||||
Inspect `go.mod`, `go.sum`, pinned ConfigKit/PromptKit module files, the v1.2.0
|
||||
consumer migration guide, and `docs/release.md`.
|
||||
|
||||
Work:
|
||||
|
||||
- Set the Go consumer minimum to 1.27.0. Use Go 1.27.0 as the selected validation
|
||||
toolchain for this sprint and update its release-runbook selection. Later
|
||||
validation-patch updates remain separate from the consumer minimum.
|
||||
- Add `go.maximumdirect.net/configkit` v1.2.0 while retaining old-path v0.5.0,
|
||||
PromptKit v0.12.0, its current catalogs, and YAML rc.6. Tidy after real imports
|
||||
land; unused new requirements may disappear before then. Retain needed graph
|
||||
changes, not arbitrary unrelated upgrades. Do not adopt ReleaseKit as a tool.
|
||||
- Verify both ConfigKit module paths and shared YAML selection. Record API compile
|
||||
errors for Stage 2 rather than repairing them with replacements or forks.
|
||||
|
||||
Acceptance: required released versions are obtainable and their graph has no
|
||||
stable-YAML plugin-removal conflict. An unexpected dependency incompatibility is
|
||||
reported with evidence rather than changing the target or upgrading PromptKit.
|
||||
|
||||
Checks: `GOTOOLCHAIN=go1.27.0 GOWORK=off go version`, selected module inspection,
|
||||
and a compilation attempt. Network/dependency preparation precedes offline tests.
|
||||
|
||||
Prompt size: dependency/toolchain preparation only.
|
||||
|
||||
## Stage 2 — Migrate Application APIs And Separate Old PromptKit Types
|
||||
|
||||
**Complete.** Application and CLI APIs now use the new module; PromptKit keeps
|
||||
the old module at its boundary. The native build, package compilation, and
|
||||
source-handoff test pass. Broader attempts exposed old control fixtures and CLI
|
||||
assignment expectations owned by later stages; CLI/LLM tests using local HTTP
|
||||
listeners also encountered this environment's socket restriction.
|
||||
|
||||
Goal: move the application loader and CLI to v1 APIs.
|
||||
|
||||
Inspect `internal/core/config/{load,loaded_config,operational_document,
|
||||
pipeline_document,document_paths,document_normalizer}.go`, CLI ConfigKit imports,
|
||||
and direct PromptKit setup under `internal/framework/llm` and test support.
|
||||
|
||||
Work:
|
||||
|
||||
- Migrate application-side imports. Update InputInfo to EntryInfo, Secret to
|
||||
Sensitive, LayerBase to LayerMain, removed diagnostic names, and generic Record
|
||||
calls to named normalization/derived-default methods. Audit stored strings too.
|
||||
- Temporarily retain sequence ancestor records where the wrapper currently emits
|
||||
them; simplify scope in Stage 3. Named recording methods record mutations already
|
||||
performed; Default/Normalize helpers both assign and record.
|
||||
- Keep old types in PromptKit-facing sources, profile inspection, and integration
|
||||
fixtures. CLI ordinary configuration errors use new LoadError/WriteDiagnostics;
|
||||
PromptKit errors remain adapted through its existing neutral facade.
|
||||
- Introduce the shared LoadSource path and MainSourcePath accessor specified above.
|
||||
Keep frozen inspection and detached runtime conversion.
|
||||
|
||||
Acceptance: production imports have explicit owners, and no mixed named types
|
||||
cross the boundary. Any remaining failures are classified as fixtures, collection
|
||||
policy, or discovery work. No upstream types enter module/runtime contracts.
|
||||
|
||||
Checks: native build to a `mktemp -d` location; focused compile/test attempts for
|
||||
`./internal/core/config ./internal/cli ./internal/framework/llm`; diff review.
|
||||
|
||||
Prompt size: API/handoff migration; no discovery implementation or broad fixtures.
|
||||
|
||||
## Stage 3 — Simplify Recorded Normalization And Preserve Source Bases
|
||||
|
||||
**Complete.** Leaf edits are recorded directly and reference paths are resolved
|
||||
before key normalization moves their source coordinates. Focused path,
|
||||
inheritance, discovered-main, and leaf-history tests pass. The full config
|
||||
suite's remaining override-order expectation is owned by fixture migration.
|
||||
|
||||
Goal: use v1.1 field-level auditing instead of old blanket sequence coverage.
|
||||
|
||||
Inspect document_normalizer.go, document_paths.go, pipeline_document.go,
|
||||
reference normalization helpers, and existing path/inheritance tests.
|
||||
|
||||
Work:
|
||||
|
||||
- Remove `inSequence`/whole-list coverage for ordinary leaf edits. Use the public
|
||||
recording helpers directly or retain only a genuinely useful thin helper.
|
||||
- Preserve explicitness and source lookup through key normalization. Resolve
|
||||
reference paths before key/record movement obscures entry addresses; retain
|
||||
only needed relocation state. Preserve true structural mutation records.
|
||||
- Verify canonical main-directory initialization against public source evidence
|
||||
and native version-path protection, including a discovered main. Retain the
|
||||
existing version-origin lookup where that contract makes it valid; avoid a
|
||||
second search. Preserve private non-file test-source handling separately.
|
||||
- Improve existing tests for imported/overlaid/inherited source bases, paths
|
||||
inside steps, whitespace-normalized IDs, CLI paths, and leaf explanation history.
|
||||
Fixtures must use distinct directories so incorrect bases cannot also pass.
|
||||
|
||||
Acceptance: leaf-only normalization is accurately recorded; real structural edits
|
||||
remain covered; runtime paths match effective output and source history. No
|
||||
new filesystem constraint or custom provenance-replay mechanism appears.
|
||||
|
||||
Checks: focused config normalization/path/inheritance tests, then all core/config
|
||||
tests when migrated fixtures allow them. Expected old control-format failures
|
||||
belong to Stage 5.
|
||||
|
||||
Prompt size: one resolution/provenance boundary.
|
||||
|
||||
## Stage 4 — Register Steps And Exercise Native Collection Semantics
|
||||
|
||||
**Complete.** Registered step IDs and verified real-file peer composition,
|
||||
upsert, replacement, append, clearing validation, inherited records, CLI list
|
||||
assignment, source-relative references, duplicate peers, and unregistered lists.
|
||||
Focused config and framework resolution tests pass. Identity-changing
|
||||
normalization records the affected list, while unchanged identities retain leaf history.
|
||||
|
||||
Goal: implement the accepted step identity and composition policy.
|
||||
|
||||
Inspect documentDefinition, pipeline step validation/conversion, ConfigKit's
|
||||
pinned sequence/placement contract, and inheritance tests.
|
||||
|
||||
Work:
|
||||
|
||||
- Add the exact wildcard registration above. Keep validation/domain IDs unchanged;
|
||||
ConfigKit owns structural identity comparison, assembly, inheritance, and history.
|
||||
- Add small real-file cases for distinct imported steps, strict duplicate peers,
|
||||
inherited/overlaid full-record upsert, replacement/append, and empty-list clearing.
|
||||
Include one identified-record inheritance case and an unregistered list showing
|
||||
that broad identity registration has not leaked elsewhere.
|
||||
- Assert resulting order, full-record replacement, and actual pipeline compatibility.
|
||||
Cover step-local references declared in different imported files and native CLI
|
||||
whole-list assignment. Do not add list merging to Notarius.
|
||||
- Use native leaf histories after composition to expose any Stage 3 defects.
|
||||
Reuse domain validation for invalid or duplicated normalized step identifiers.
|
||||
|
||||
Acceptance: native composition produces the intended typed pipeline and existing
|
||||
domain rules still apply. Default upsert and explicit replace differ as documented.
|
||||
|
||||
Checks: config collection/inheritance tests and focused framework resolution tests.
|
||||
|
||||
Prompt size: one definition registration and its focused behavior coverage.
|
||||
|
||||
## Stage 5 — Migrate Application Fixtures And Restore Configuration Coverage
|
||||
|
||||
**Complete.** Application fixtures and expectations now use native controls,
|
||||
post-decode overrides, and identified step operations; PromptKit fixtures remain
|
||||
on its old format. Config and LLM suites pass. CLI tests compile and pass apart
|
||||
from maintained-example cases reserved for the example migration.
|
||||
|
||||
Goal: translate existing tests to the selected source contract.
|
||||
|
||||
Inspect config document/operational/loaded/paths/inheritance tests and CLI
|
||||
ConfigKit/command/production tests. Discover literals and helpers by consumer.
|
||||
|
||||
Work:
|
||||
|
||||
- Rename genuine application-source controls to `config` and update stored pointer
|
||||
and layer strings. Required file fixtures explicitly declare requiredness; tests
|
||||
of absent optional imports adopt the native default. Keep old PromptKit sources
|
||||
and their fixtures under the old reader's syntax and APIs.
|
||||
- Update tests deliberately for post-decode CLI assignment and identified step
|
||||
upsert. A CLI override does not repair decoding/structural errors. An explicitly
|
||||
replaced empty list, null, omission, and empty append/upsert have distinct meanings.
|
||||
- Preserve version checks, application field validation, dynamic integer option
|
||||
conversion, redaction, cancellation, and detached runtime/inspection ownership.
|
||||
Include nested ordinary `config` data in dynamic options to protect control scope.
|
||||
- Consolidate small fixtures only when it reduces duplication without disguising
|
||||
the two loader versions. No generic legacy-to-new YAML converter belongs in tests.
|
||||
|
||||
Acceptance: existing application configuration coverage exercises v1.2.0 with
|
||||
intentional semantic changes documented in tests; LLM fixtures still use old types.
|
||||
|
||||
Checks: `GOWORK=off go test ./internal/core/config ./internal/framework/llm` plus
|
||||
CLI compile/tests, noting discovery assertions assigned to Stages 6–7.
|
||||
|
||||
Prompt size: mechanical fixture migration; avoid unrelated production refactoring.
|
||||
|
||||
## Stage 6 — Delegate CLI Discovery And Publish The Actual Selected File
|
||||
|
||||
**Complete.** The shared CLI loader selects one ConfigKit source and reports
|
||||
the retained main path; manual probing was removed. Focused load, selection,
|
||||
diagnostic, and report tests and a native temporary build pass. The expanded
|
||||
discovery matrix is covered separately below.
|
||||
|
||||
Goal: replace filesystem probing with the settled native source selection.
|
||||
|
||||
Inspect loadConfigKit, discoverConfigPath/requireConfigFile, command dispatch,
|
||||
Options.LookupEnv, and invocation/debug use of loadedConfigPath.
|
||||
|
||||
Work:
|
||||
|
||||
- Construct exclusive File or ordered required SearchConfig sources as specified.
|
||||
Pass one source to LoadSource. Remove obsolete stat/probe loops and single-default
|
||||
constants once unused. Keep blank optional flag/environment handling consistent.
|
||||
- Populate the selected-path return from MainSourcePath. Preserve canonical
|
||||
source-relative application defaults and the actual path in requested debug data.
|
||||
- Route load failures through new ConfigKit structured diagnostics/source legends.
|
||||
Keep ordinary syntax exit 2 and acquisition/validation exit 1 behavior; do not
|
||||
parse diagnostic prose. Retain old PromptKit error handling for its own reports.
|
||||
- Update all run/config/report/list callers through the shared boundary. Do not
|
||||
resolve pipelines or call providers merely to discover/report configuration.
|
||||
|
||||
Acceptance: no manual file search precedes ConfigKit; every config-consuming
|
||||
command uses the same selected source and its retained provenance.
|
||||
|
||||
Checks: focused CLI load/discovery/report tests and native build.
|
||||
|
||||
Prompt size: shared CLI loading boundary, not the full discovery test matrix.
|
||||
|
||||
## Stage 7 — Verify Discovery, Inspection, And Failure Semantics
|
||||
|
||||
**Complete.** Controlled discovery tests cover precedence, filename ordering,
|
||||
terminal failures, canonical symlinks, required exhaustion, reports, and the
|
||||
selected path recorded by an injected-client run. Focused tests pass; the broader
|
||||
CLI suite still awaits the maintained-example migration.
|
||||
|
||||
Goal: protect the new operator contract with bounded offline coverage.
|
||||
|
||||
Inspect CLI command_contract/configkit_load/configkit_commands tests and
|
||||
core/config loaded/source tests. Use real CWD/user-directory behavior in tests
|
||||
that control process state and are not parallel.
|
||||
|
||||
Work:
|
||||
|
||||
- Cover CLI over environment, environment over discovery, CWD over user selection,
|
||||
native named-file ordering, and the absence of generic CWD config.yml selection.
|
||||
Bad explicitly selected files and invalid selected CWD files fail without fallback.
|
||||
- Isolate user directories with controlled platform environment. Avoid tests that
|
||||
write /etc or depend on the host's system configuration. Rely on upstream for
|
||||
preset directory expansion; test required-search exhaustion with a controlled
|
||||
SearchConfig passed to LoadSource rather than assuming host directories are empty.
|
||||
- Verify selected-file path and declaring-directory defaults after discovery,
|
||||
source-local overlays/imports, canonical symlink source behavior, and CLI paths.
|
||||
- Exercise effective/explain/validate/list and a recorded run with an injected
|
||||
external client. Assert safe source diagnostics, origins, provider-free reports,
|
||||
ordinary optional absence without warnings, and unchanged PromptKit scoped reports.
|
||||
|
||||
Acceptance: selection precedence and terminal failures are observable through
|
||||
commands without a second acquisition pass or host-dependent fixtures.
|
||||
|
||||
Checks: `GOWORK=off go test ./internal/core/config ./internal/cli ./internal/framework/llm`.
|
||||
|
||||
Prompt size: discovery and cross-boundary behavioral verification.
|
||||
|
||||
## Stage 8 — Maintain Runnable Native Composition Examples
|
||||
|
||||
**Complete.** The complete example imports its first step as a required native
|
||||
sequence item; existing order, handoff, and inheritance assertions pass. The
|
||||
CLI and module-integration suites and credential-free minimal, complete, and
|
||||
development validation pass. An old missing-source diagnostic assertion was
|
||||
also updated to match the delegated loader.
|
||||
|
||||
Goal: demonstrate the approved features in the existing two top-level examples.
|
||||
|
||||
Inspect examples/dnd-complete.config.yml, pipelines/dnd-session.yml, development
|
||||
overlay, profile file, and internal/cli/example_contract_test.go.
|
||||
|
||||
Work:
|
||||
|
||||
- Change the complete root's import to `config` and make it explicitly required.
|
||||
- Move its describe-session step into a new sibling fragment
|
||||
`examples/pipelines/dnd-session.describe-session.yml`, containing the step mapping.
|
||||
The pipeline fragment imports it with `required: true`,
|
||||
`destination: [pipelines, dnd-session, steps]`, and `placement: sequence-item`;
|
||||
retain extract-events in the declaring fragment's steps list. Native dependency-
|
||||
ready composition places the imported first step before the declaring body.
|
||||
- Keep the new fragment beside the old one so existing file-relative references
|
||||
retain their bases. Preserve lane IDs, module options, generated references,
|
||||
pipeline behavior, and the derived development profile. Leave the old PromptKit
|
||||
deployment document's syntax unchanged.
|
||||
- Update example tests to resolve the complete/development pipelines, assert actual
|
||||
step order and handoffs, and validate without credentials/inference. Retain exactly
|
||||
the existing two top-level examples; the added fragment is supporting content.
|
||||
|
||||
Acceptance: maintained configurations load natively and demonstrate composed steps
|
||||
plus inheritance with no duplicated complete pipeline or altered D&D execution policy.
|
||||
|
||||
Checks: existing CLI example tests and module-integration tests; credential-free
|
||||
CLI validation of minimal, complete, and development selections.
|
||||
|
||||
Prompt size: one supporting fragment and existing example coverage.
|
||||
|
||||
## Stage 9 — Update Operator And Consumer Documentation
|
||||
|
||||
**Complete.** Operator references now describe native discovery, composition,
|
||||
override timing, path bases, and the separate PromptKit format. Source-install,
|
||||
release-validation, and advisory CI toolchain guidance select Go 1.27.0.
|
||||
Maintained-example resolution and validation tests pass.
|
||||
|
||||
Goal: document implemented native behavior and migration in canonical homes.
|
||||
|
||||
Work:
|
||||
|
||||
- Update docs/config.md for selected-source order/filename groups, root controls,
|
||||
optional imports/explicit requiredness, step identity/upsert/replace/append,
|
||||
record inheritance, destinations, native CLI timing, and path bases. Remove
|
||||
obsolete universal whole-list-replacement/step-inheritance limitations.
|
||||
- Update docs/cli.md discovery and report behavior, linking to config's field rules.
|
||||
Keep explicit --config advice first-class in subprocess/operations guidance.
|
||||
- Explain the two configuration formats at the temporary boundary: Notarius uses
|
||||
new controls, PromptKit operator documents still follow its old engine. Show
|
||||
concise migration snippets and link the maintained complete files.
|
||||
- Update README's consumer-minimum rationale for the newly selected ConfigKit
|
||||
requirement and release setup to Go 1.27.0. Keep source-only publication and
|
||||
existing release gates. Update actual CI toolchain configuration if present;
|
||||
create no new CI workflow or publication mechanism.
|
||||
|
||||
Acceptance: operator guidance explains real new semantics and intentional migration
|
||||
without introducing extra import restrictions or promising unchanged composition.
|
||||
|
||||
Checks: relevant example tests, link/command review, and `git diff --check`.
|
||||
|
||||
Prompt size: public references and concise consumer/workflow adjustments.
|
||||
|
||||
## Stage 10 — Update Integration References And Attribution
|
||||
|
||||
**Complete.** Internal and integration references describe the selected-source
|
||||
handoff and mixed dependency ownership. Attribution records both ConfigKit
|
||||
module identities against their pinned notices. Selected module and compiled
|
||||
dependency inspection found no additional runtime component; upstream release
|
||||
tooling remains unadopted. Module metadata was tidied after the imports landed.
|
||||
|
||||
Goal: make ownership and the temporary mixed graph accurately documented.
|
||||
|
||||
Work:
|
||||
|
||||
- Update docs/internal/configuration.md and docs/internal/cli.md for LoadSource,
|
||||
selected-path provenance, field-level resolution, discovery, and source parity.
|
||||
Remove stale blanket-list-recording and manual search descriptions.
|
||||
- Update docs/integrations/pkg-configkit.md to v1.2.0/new module/pinned contracts.
|
||||
Explain the temporary old dependency in the PromptKit/LLM integration references
|
||||
without documenting its entire future migration. ADR-0020 already owns the decision.
|
||||
- Update docs/oss/attribution.md for new ConfigKit at the full source commit,
|
||||
retain its old-path dependency's notice, and review actually selected transitive
|
||||
modules/tool requirements. Inspect released COPYRIGHT/LICENSE/notices; reuse
|
||||
unchanged standard texts. Preserve the project grant and policy provenance.
|
||||
- Keep upstream release tooling and its gates upstream. Dependency attribution
|
||||
does not adopt ReleaseKit as Notarius's release implementation.
|
||||
|
||||
Acceptance: current docs and factual notices match the selected mixed graph;
|
||||
historical ADRs/releases remain untouched. No policy or license grant is expanded.
|
||||
|
||||
Checks: selected module inspection, pinned/local link and notice review, whitespace
|
||||
check. Reuse unchanged example validation rather than adding documentation snapshots.
|
||||
|
||||
Prompt size: focused internal/integration docs and dependency notices.
|
||||
|
||||
## Stage 11 — Verify The Entire Target And Finish The Sprint
|
||||
|
||||
**Complete.** The final offline `go test ./...`, `go vet ./...`, and
|
||||
`go mod tidy -diff` pass with Go 1.27.0 and `GOWORK=off`; the test run permits
|
||||
local HTTP listeners. A temporary native build validates the maintained minimal,
|
||||
complete, and development selections and both application and PromptKit
|
||||
inspection reports without provider calls. Module inspection confirms ConfigKit
|
||||
v1.2.0 and v0.5.0, PromptKit v0.12.0, and YAML v4.0.0-rc.6. A final direct
|
||||
identified-record inheritance regression supplements the composition coverage.
|
||||
No production inference, publication, or deferred dependency upgrade was performed.
|
||||
|
||||
Goal: prove all feature-roadmap acceptance on the completed implementation.
|
||||
|
||||
Work:
|
||||
|
||||
- Compare final code, examples, tests, and docs against each target section.
|
||||
Check new ConfigKit v1.2.0, old v0.5.0 for PromptKit, YAML rc.6, unchanged PromptKit
|
||||
v0.12.0/catalogs, Go minimum/toolchain, native controls, discovery, step composition,
|
||||
sources/paths, leaf histories, and frozen inspection. Correct small residual defects.
|
||||
- Review remaining old imports/control strings by owner, not a blanket grep ban.
|
||||
Old PromptKit APIs and historical release text legitimately remain. Remove obsolete
|
||||
application wrappers/probing and contradictions; retain meaningful behavioral tests.
|
||||
- Run full offline tests, vet, tidy diff, native temporary build, and source/version
|
||||
inspection. Smoke-test config validate on all maintained selections and both
|
||||
ordinary/PromptKit inspection reports. Use explicit fixture input only for offline
|
||||
injected-client run tests; do not invoke a production pipeline for verification.
|
||||
- Review accidental strengthening: no extra permissions, mandatory secret lookup,
|
||||
fragment-version requirement, stricter import defaults, hidden list merger,
|
||||
compatibility shim, or new release gate. Leave unrelated prior findings and
|
||||
roadmap retirement to their own work sets.
|
||||
- Report actual checks and remaining limitations. Upgrade completion requires a
|
||||
buildable graph and passing target behavior, not only a successful go get.
|
||||
|
||||
Validation commands, with dependencies prepared and Go 1.27.0 selected:
|
||||
|
||||
```sh
|
||||
GOWORK=off go test ./...
|
||||
GOWORK=off go vet ./...
|
||||
GOWORK=off go mod tidy -diff
|
||||
GOWORK=off go list -m go.maximumdirect.net/configkit gitea.maximumdirect.net/eric/ConfigKit gitea.maximumdirect.net/eric/promptkit go.yaml.in/yaml/v4
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Build ./cmd/notarius beneath a mktemp directory outside the repository. These
|
||||
are sprint verification steps, not added permanent release gates. No file changes
|
||||
means no empty final commit. Release numbering, notes/publication, ConfigKit
|
||||
v1.2.1/stable YAML, and the full PromptKit upgrade remain separate work.
|
||||
|
||||
Prompt size: final evidence review and small cleanup; significant newly discovered
|
||||
scope requires an explicit decision rather than silently narrowing acceptance.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None. The intermediate version, source selection, step identity, and native
|
||||
configuration policies are approved. The mixed graph remains an early technical
|
||||
verification task; report a concrete incompatibility if one appears instead of
|
||||
silently selecting another version or adding compatibility machinery.
|
||||
@@ -10,8 +10,7 @@ or changing Notarius's domain extraction and pipeline acceptance policies.
|
||||
|
||||
This is a feature roadmap, not an execution sequence. The operator-source and
|
||||
native-overlay decisions were accepted on 2026-10-04 and are incorporated below.
|
||||
The [implementation plan](implementation.md) owns the ordered work and
|
||||
verification sequence. Release preparation and publication are separate work.
|
||||
Release preparation and publication are separate work.
|
||||
|
||||
## Reviewed Baseline
|
||||
|
||||
|
||||
@@ -1,549 +0,0 @@
|
||||
# Configuration Upgrade Review Remediation
|
||||
|
||||
All eight findings were completed on 2026-11-18, with one commit per finding.
|
||||
Assessment and evidence paragraphs below retain their review-time context;
|
||||
each finding's completion marker records the implemented resolution.
|
||||
|
||||
Final verification passed: full offline tests, vet, race checks for configuration,
|
||||
CLI and LLM packages, module tidy consistency, a native temporary build, and
|
||||
credential-free minimal/complete/development configuration and inspection checks.
|
||||
|
||||
The earlier PromptKit findings below retain their original scope and status.
|
||||
The ConfigKit 1.2.0 review and subsequent focused audits appear below; they
|
||||
do not reopen or attribute earlier issues to that upgrade.
|
||||
|
||||
## Scope And Overall Assessment
|
||||
|
||||
Review baseline: Notarius `6700ed2`, compared with planning revision `f5b066b`,
|
||||
the accepted [feature roadmap](promptkit.md), and
|
||||
[implementation plan](implementation.md). PromptKit v0.12.0 is pinned at
|
||||
`4b8169da286917fde7875425bb32b799b12c6af3`; ConfigKit remains v0.5.0, with both
|
||||
PromptKit `/v3` catalogs at v3.20260930.0.
|
||||
|
||||
The migration is substantially implemented. Native sources, combined operator
|
||||
documents and imports, recursive overlays, source-relative prompt content,
|
||||
captured engine lifetime, immutable checkpoint identity, and credential-free
|
||||
operator inspection are in place. The provider-neutral execution boundary,
|
||||
prepared execution, retries, scheduling, and durable artifact contracts remain
|
||||
intact. All 16 migrated prompt bodies match the previous definitions after
|
||||
removing their old embedded identity fields; prompt fragments and schemas are
|
||||
unchanged.
|
||||
|
||||
Four bounded follow-ups remain below. No production code is changed by this
|
||||
review. No additional runtime security restriction, mandatory credential check,
|
||||
filesystem permission policy, compatibility shim, or release gate was found.
|
||||
Eager final-definition validation and the external keyed format are intentional
|
||||
upstream changes, not accidental strengthening. The previously recorded
|
||||
ConfigKit remediation was completed before this work set; it is not outstanding.
|
||||
|
||||
## Finding 1 — Compose Registered Application Assets In One Strict Group
|
||||
|
||||
Priority: P2. Category: architecture/correctness gap. Status: complete.
|
||||
|
||||
Completed 2026-11-18: combined application filesystem inputs into one strict
|
||||
underlay, retaining their independent contexts. Added conflict/operator-overlay
|
||||
coverage; LLM, CLI, and module suites pass, including source-relative content tests.
|
||||
|
||||
Evidence:
|
||||
|
||||
- `internal/framework/llm/asset_registry.go:106–139` creates one underlay per
|
||||
registered prompt or fallback-profile filesystem.
|
||||
- `internal/framework/llm/asset_registry_sources_test.go`,
|
||||
`TestPromptKitConfigurationSourcesKeepsNativeFilesystemGroups`, asserts that
|
||||
separate registrations yield separate underlays, encoding this divergence.
|
||||
- The plan's Sources And Engine Ownership section calls for one application
|
||||
underlay whose inputs each retain their own filesystem context;
|
||||
`docs/internal/llm.md:86–92` also describes that behavior.
|
||||
|
||||
Separate underlays have recursive overlay semantics. Conflicting application
|
||||
definitions in different registrations therefore silently depend on module
|
||||
registration order instead of receiving native strict-composition diagnostics.
|
||||
An offline probe registered two fallback files with the same profile key and
|
||||
different models. The current inspector accepted them and selected the second
|
||||
model. The exact same filesystem inputs placed in one native underlay correctly
|
||||
failed composition. Distinct filesystem contexts do not require separate layers.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Gather the native `FilesystemInputs` from every application prompt and
|
||||
fallback-profile registration into one application underlay. Preserve each
|
||||
input's existing label, filesystem, root, and disabled-import setting. Keep
|
||||
schemas on their separate runtime option and omit an empty application group.
|
||||
- Keep the operator and explicit local-backend contributions as later groups.
|
||||
Preserve their accepted recursive overrides and source precedence. Do not
|
||||
add an application-specific duplicate-key detector or flatten filesystem
|
||||
contexts into an artificial shared root.
|
||||
- Replace the incidental group-count test with behavioral coverage: conflicting
|
||||
application contributions fail through native strict composition; distinct
|
||||
declarations retain source-relative content; an operator overlay over the
|
||||
resulting application base still succeeds. Reuse existing origin coverage.
|
||||
|
||||
Acceptance: application conflicts are not silently resolved by registration
|
||||
order; source-relative imports/content and valid later operator overlays remain
|
||||
unchanged. Runtime, preflight, and reports use the corrected shared construction.
|
||||
|
||||
Validation: `GOWORK=off go test ./internal/framework/llm ./internal/cli ./internal/modules/...`.
|
||||
|
||||
## Finding 2 — Validate Explanation Syntax Before Loading Configuration
|
||||
|
||||
Priority: P3. Category: CLI correctness. Status: complete.
|
||||
|
||||
Completed 2026-11-18: both scopes validate canonical pointer syntax before
|
||||
loading configuration. Missing-file regression and CLI/LLM suites pass.
|
||||
|
||||
Evidence: `internal/cli/configkit_commands.go:77–106`. PromptKit scope loads
|
||||
Notarius configuration and constructs the inspection engine before validating
|
||||
the pointer; the default Notarius scope parses the pointer first.
|
||||
|
||||
Reproduction, using the native temporary build and a nonexistent config path:
|
||||
|
||||
```sh
|
||||
notarius config explain --scope promptkit --config /path/to/missing.yml '/profiles/~2'
|
||||
```
|
||||
|
||||
The current PromptKit command returns exit 1 with a config-file error. The same
|
||||
malformed pointer returns exit 2 with a valid config, and the Notarius scope
|
||||
returns exit 2 even with the missing config. A bad PromptKit definition or
|
||||
missing content file can likewise mask malformed command syntax. This differs
|
||||
from the selected syntax/runtime distinction in the plan and CLI reference.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Validate canonical JSON Pointer syntax once, before either scope loads config
|
||||
or constructs an engine. Reuse the existing parser; retain defensive parsing
|
||||
inside the adapter for direct callers.
|
||||
- Keep the empty root pointer, escaped literal keys, historical-only paths,
|
||||
unknown-path exit 1, and writer-error behavior unchanged.
|
||||
- Extend CLI coverage with a malformed pointer and unavailable configuration;
|
||||
verify exit 2, no stdout, and no configuration/provider work. No broader
|
||||
argument-parser refactor is needed.
|
||||
|
||||
Acceptance: malformed pointers are syntax errors independent of configuration
|
||||
availability for both scopes; valid selectors still load and inspect normally.
|
||||
|
||||
Validation: `GOWORK=off go test ./internal/cli ./internal/framework/llm`.
|
||||
|
||||
## Finding 3 — Correct Lifecycle And Fallback Documentation
|
||||
|
||||
Priority: P3. Category: documentation accuracy. Status: complete.
|
||||
|
||||
Completed 2026-11-18: corrected construction/preparation timing, fallback overlay
|
||||
semantics, and operator/local-backend alternatives in comments and canonical docs.
|
||||
Checked against current source construction and existing passing inspection tests;
|
||||
affected links and whitespace checks pass. No runtime behavior changed.
|
||||
|
||||
Evidence:
|
||||
|
||||
- `docs/config.md:321–323` says prompt **and schema** definitions are validated
|
||||
at engine construction. Schemas remain preparation-time resources supplied
|
||||
through `WithSchemaFS`, not captured configuration definitions.
|
||||
- `docs/internal/llm.md:71–77` and `docs/internal/cli.md:55–61` describe preflight
|
||||
as occurring without loading a prompt. Construction now loads and validates
|
||||
effective prompt definitions and captures message files/static templates;
|
||||
it does not prepare a request or generate output.
|
||||
- The comment on `RegisterFallbackProfileFS` in
|
||||
`internal/framework/llm/asset_registry.go:61–62` still says fallback assets
|
||||
are used only when the operator source lacks the ID. Under recursive overlays,
|
||||
their omitted fields remain active beneath a matching operator entry.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Distinguish constructor-time definition/message capture from preparation-time
|
||||
schema loading and request-variable/artifact resolution. State accurately
|
||||
that preflight needs no transcript, credential value, or provider call; do
|
||||
not promise it performs no prompt-content file reads.
|
||||
- Describe fallback registration as a lower-precedence application contribution
|
||||
rather than an all-or-nothing lookup fallback.
|
||||
- While editing this text, clarify that an operator `backends.local` declaration
|
||||
can supply the backend as well as Notarius's optional `local_backend` object.
|
||||
The latter is a convenience contribution, not a required second declaration.
|
||||
Link canonical source rules rather than duplicating them.
|
||||
- Change documentation/comments only unless verification exposes a real runtime
|
||||
defect. Do not move schema loading earlier to make the stale prose true.
|
||||
|
||||
Acceptance: public and internal guidance consistently explains actual lifecycle,
|
||||
native layering, and operator backend configuration without inventing a stronger
|
||||
preflight guarantee or an additional required config field.
|
||||
|
||||
Validation: inspect current constructors/prepared execution and upstream v0.12
|
||||
contracts; review affected local links; run `git diff --check`. Reuse unchanged
|
||||
behavioral checks rather than adding prose-snapshot tests.
|
||||
|
||||
## Finding 4 — Preserve ADR-0010's Historical Decision Body
|
||||
|
||||
Priority: P3. Category: documentation-policy compliance. Status: complete.
|
||||
|
||||
Completed 2026-11-18: restored the original body from f5b066b, retaining only
|
||||
the approved status/supersession change. Baseline diff and link checks pass.
|
||||
|
||||
Evidence: the migration diff rewrites ADR-0010's Decision and Consequences
|
||||
paragraphs at `docs/adr/0010-workload-oriented-llm-profile-defaults.md:26–33`
|
||||
and `:47–50`, as well as adding the appropriate status/supersession link.
|
||||
`docs/policy/documentation.md` requires accepted decision content to remain
|
||||
immutable; Stage 14 specified a concise status link rather than rewriting the
|
||||
historical body.
|
||||
|
||||
The replacement correctly acknowledges the old behavior, but the historical
|
||||
record should retain its original wording. ADR-0019 already owns the new native
|
||||
overlay decision and accurately limits which part of ADR-0010 it supersedes.
|
||||
|
||||
Required change: restore ADR-0010's Decision and Consequences body from `f5b066b`,
|
||||
keeping its new partial-supersession status and ADR-0019 link. Leave workload
|
||||
ownership and ADR-0019 unchanged. Current runtime behavior remains documented
|
||||
in the canonical current references, not retrofitted into the older decision.
|
||||
|
||||
Acceptance: the historical body matches the accepted original, the changed
|
||||
clause's supersession remains discoverable, and no runtime behavior changes.
|
||||
|
||||
Validation: compare the body with `git show f5b066b:docs/adr/0010-workload-oriented-llm-profile-defaults.md`,
|
||||
verify the ADR link, and run `git diff --check`.
|
||||
|
||||
## Review Evidence And Validation
|
||||
|
||||
- `GOWORK=off go test ./...` passed.
|
||||
- `GOWORK=off go vet ./...` passed.
|
||||
- `GOWORK=off go test -race ./internal/framework/llm ./internal/cli` passed.
|
||||
- `GOWORK=off go mod tidy -diff` produced no changes.
|
||||
- Module inspection confirmed the selected ConfigKit, PromptKit, and catalog pins.
|
||||
- A native build outside the repository succeeded. Credential-free profile and
|
||||
explanation commands and complete/development pipeline validation succeeded.
|
||||
- A YAML-aware comparison confirmed all 16 migrated prompt definition bodies
|
||||
are unchanged after removing old embedded IDs/versions. Prompt fragments,
|
||||
schemas, and the embedded D&D execution settings are unchanged.
|
||||
- An offline Go overlay probe, stored entirely outside the repository, confirmed
|
||||
the application-group conflict behavior in Finding 1. CLI invocations
|
||||
reproduced Finding 2 without generation or provider calls.
|
||||
- The implementation diff passed whitespace checks. No production inference
|
||||
or production model-quality evaluation was performed.
|
||||
|
||||
Recommended remediation is limited to these findings, not another configuration
|
||||
system, new security policy, or unrelated pipeline refactoring.
|
||||
|
||||
## ConfigKit 1.2.0 Review
|
||||
|
||||
Reviewed on 2026-11-17 against implementation revision `c9744ad`, compared with
|
||||
planning revision `79088a3` and the ConfigKit feature roadmap and implementation
|
||||
plan. The subsequent roadmap-only clarification in `d88a01c` does not change
|
||||
the reviewed runtime. ConfigKit v1.2.0 resolves to
|
||||
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`.
|
||||
|
||||
The production architecture matches the target. Application configuration uses
|
||||
new-path ConfigKit v1.2.0; the unchanged PromptKit v0.12.0 adapter retains
|
||||
old-path ConfigKit v0.5.0. Both use YAML v4.0.0-rc.6 under Go 1.27.0. The CLI
|
||||
describes one exclusive file or ordered native search source, while ConfigKit
|
||||
owns acquisition, imports, collections, inheritance, decoding, diagnostics, and
|
||||
inspection. Notarius supplies domain defaults, recorded normalization,
|
||||
validation, detached runtime conversion, and catalog-dependent resolution.
|
||||
|
||||
No new production correctness defect or unwarranted restriction was found.
|
||||
The changed controls, optional import defaults, post-decode CLI assignments,
|
||||
step identity/upsert, search behavior, and higher Go minimum are approved scope.
|
||||
The remaining gaps are two operator-documentation inaccuracies from Stage 9,
|
||||
also missed by Stage 11's final documentation check. Production fixes are not
|
||||
required for either finding.
|
||||
|
||||
### Finding CK-1 — Distinguish Mapping And Record Inheritance Syntax
|
||||
|
||||
Priority: P3. Category: documentation accuracy. Status: complete.
|
||||
|
||||
Completed 2026-11-18: documented both reference forms and their lookup scopes,
|
||||
linking to the pinned native examples. Checked against v1.2.0's contract and
|
||||
existing inheritance coverage; no non-executable example was added.
|
||||
|
||||
Evidence: `docs/config.md:143–149` introduces both mapping and identified-record
|
||||
inheritance, then says a directive names an immediate sibling in the same
|
||||
mapping. That describes mapping inheritance only. For an identified step record,
|
||||
the parent belongs to the same sequence and the reference must be an identity
|
||||
mapping, such as `extends: {id: parent}`. The reference never shows that form.
|
||||
|
||||
An offline CLI probe with a parent step providing references and a child step
|
||||
providing an artifact lane confirmed that `extends: parent` fails with
|
||||
`inheritance.invalid`, while changing only the directive to
|
||||
`extends: {id: parent}` loads successfully and preserves the inherited reference.
|
||||
`TestIdentifiedStepRecordInheritance` already exercises the correct form in
|
||||
`internal/core/config/collection_composition_test.go:182–208`.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Explain string-valued mapping-sibling inheritance and identity-mapping
|
||||
sequence-record inheritance separately, including their distinct lookup scopes.
|
||||
- Add a minimal step-record example or a direct link to the pinned upstream
|
||||
syntax example. Preserve the existing rules for null cancellation, validation,
|
||||
and whole-record upsert; no new application inheritance machinery is needed.
|
||||
|
||||
Acceptance: an operator can determine the correct syntax for both a pipeline
|
||||
mapping and an identified record from the canonical reference. Any example
|
||||
presented as a runnable pipeline must pass pipeline resolution, not just loading;
|
||||
see CK-3 for step-record limitations. Reuse behavioral coverage rather than adding
|
||||
a documentation snapshot or changing runtime behavior to fit the prose.
|
||||
|
||||
### Finding CK-2 — Describe Dependency-Ready Step Assembly Order
|
||||
|
||||
Priority: P3. Category: documentation accuracy. Status: complete.
|
||||
|
||||
Completed 2026-11-18: replaced the source-order claim with native dependency-ready
|
||||
assembly, linked the pinned contract, and explained the complete example's ordering.
|
||||
Verified against the pinned scheduler contract and unchanged example assertions.
|
||||
|
||||
Evidence: `docs/config.md:167–170` says distinct imported step IDs combine
|
||||
"in source order." ConfigKit distinguishes acquisition/import declaration order
|
||||
from dependency-ready assembly order. Ready contributions are selected by their
|
||||
stable source keys, so independent branches can interleave. The feature roadmap
|
||||
and Stage 8 correctly rely on dependency-ready assembly rather than a Notarius
|
||||
append pass.
|
||||
|
||||
An offline CLI probe declared imports in the order `z-first.yml`, then
|
||||
`a-second.yml`, each contributing a different step and lane. Effective output
|
||||
placed the step from `a-second.yml` first, then the step from `z-first.yml`.
|
||||
Thus declaration order does not determine the resulting step list. This matters
|
||||
because Notarius executes steps in the resolved list order and validates their
|
||||
generated-reference dependencies.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Replace the source-order claim with the native dependency-ready assembly rule
|
||||
and link to ConfigKit v1.2.0's pinned composition contract for its full ordering
|
||||
semantics. Do not promise declaration order or duplicate the upstream scheduler.
|
||||
- Explain briefly why the maintained complete example's imported describe-session
|
||||
step precedes the importing body's extract-events step: the imported dependency
|
||||
is assembled before its importer. Keep the canonical operator rule in
|
||||
`docs/config.md`; other documentation should link rather than redefine it.
|
||||
|
||||
Acceptance: the reference does not imply that reordering independent import
|
||||
declarations necessarily reorders steps. The complete example's actual step
|
||||
order and generated-reference handoffs remain unchanged. No custom sorting,
|
||||
merging, or scheduler changes belong in this remediation.
|
||||
|
||||
### Stage-By-Stage Review Evidence
|
||||
|
||||
| Stage | Review result |
|
||||
| --- | --- |
|
||||
| 1 — Dependencies/toolchain | The selected graph builds with Go 1.27.0, both approved ConfigKit versions, PromptKit v0.12.0, and YAML rc.6; tidy reports no diff. |
|
||||
| 2 — API/handoff | Application imports use the new package, old types remain in the PromptKit boundary, and LoadSource/MainSourcePath retain frozen inspection and detached runtime values. |
|
||||
| 3 — Normalization/origins | Paths resolve before key movement; unchanged step identities retain leaf records, changed identities retain covering structural records. Existing tests and an additional temporary combined key/path-normalization probe pass. |
|
||||
| 4 — Collections | The exact step-only identity registration delegates composition to ConfigKit. Real-file tests cover imports, upsert, replace, append, clearing, and source-relative references. Identified-record inheritance is checked only at loading/configuration validation; CK-3 records the missing runtime-consumer check. |
|
||||
| 5 — Fixtures | Application fixtures use native controls and assignment timing; old PromptKit fixtures remain correctly scoped. The full suite passes. |
|
||||
| 6 — CLI discovery | The shared loader describes File/SearchConfig sources once and returns the recorded selected file. Manual probe helpers are removed. |
|
||||
| 7 — Discovery/failures | Controlled tests cover precedence, filename selection, required exhaustion, terminal failures, reports, symlinks, and debug provenance without relying on host system files. |
|
||||
| 8 — Examples | Minimal, complete, and development pipelines validate without inference; the supporting fragment preserves module choices, step order, and handoffs. |
|
||||
| 9 — Operator docs | Search, controls, path bases, CLI timing, and toolchain guidance are updated. CK-1 and CK-2 remain. |
|
||||
| 10 — Internal/integration docs and notices | The mixed dependency boundary and pinned ConfigKit attribution match the selected graph. Accepted ADRs, policy, and project license/grant were not modified by the sprint. |
|
||||
| 11 — Final verification | Full tests, vet, tidy, native build, dependency inspection, and provider-free validation/effective/explanation commands pass. The final documentation review missed CK-1 and CK-2. |
|
||||
|
||||
### ConfigKit Review Validation
|
||||
|
||||
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go test ./...` passed.
|
||||
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go vet ./...` passed.
|
||||
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go test -race ./internal/core/config ./internal/cli` passed.
|
||||
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go mod tidy -diff` produced no changes.
|
||||
- A native build in a temporary directory succeeded. Minimal, complete, and
|
||||
development configuration validation, plus application and PromptKit effective
|
||||
and explanation reports, succeeded without provider calls.
|
||||
- Selected module inspection confirmed the four approved ConfigKit, PromptKit,
|
||||
and YAML versions. Pinned local upstream documentation and notices were checked.
|
||||
- Temporary fixtures outside the repository reproduced both documentation gaps
|
||||
and verified combined identifier/reference-path normalization. No production
|
||||
pipeline, credential lookup, or live model-quality evaluation was performed.
|
||||
- The review document passed `git diff --check`; production code and current
|
||||
operator documentation were not changed by this review.
|
||||
|
||||
Keep the earlier PromptKit findings separate from these two documentation fixes.
|
||||
The deferred PromptKit/ConfigKit v1.2.1 upgrade and release work remain out of scope.
|
||||
|
||||
## ConfigKit Integration Audit
|
||||
|
||||
Reviewed on 2026-11-17 against `6f0a75e`, with particular attention to how the
|
||||
11 implementation stages interact with the existing pipeline and PromptKit
|
||||
consumers. The implementation is unchanged from `c9744ad`; the intervening
|
||||
commits changed roadmaps only. CK-1 and CK-2 remain open.
|
||||
|
||||
The dependency/toolchain boundary, detached configuration conversion, path
|
||||
normalization, CLI overrides, native discovery, selected-file reporting, and
|
||||
old-format PromptKit source handoff are coherent. The maintained complete
|
||||
example still reaches the existing multi-step runner and publishes its generated
|
||||
registry/occurrence handoffs through an injected external client. Session,
|
||||
checkpoint, warning, and output consumers continue to receive resolved domain
|
||||
values, not ConfigKit source graphs. No new production correctness regression
|
||||
was identified. One additional test/documentation integration gap remains.
|
||||
|
||||
### Finding CK-3 — Verify Identified-Record Inheritance At The Runtime Boundary
|
||||
|
||||
Priority: P3. Category: integration coverage and support-scope clarity. Status: complete.
|
||||
|
||||
Completed 2026-11-18: reframed the reference-only step fixture as a negative
|
||||
resolution case and added compatible validator-record inheritance that reaches
|
||||
Config.Resolve and verifies inherited options. Documented step/lane constraints
|
||||
without relaxing them. Core configuration and CLI/example suites pass.
|
||||
Affected stages: 4, 9, and 11.
|
||||
|
||||
`TestIdentifiedStepRecordInheritance` in
|
||||
`internal/core/config/collection_composition_test.go:182–208` supplies a parent
|
||||
step containing only references and a child step containing an artifact lane.
|
||||
It checks `Load` and `Config.Validate`, but never calls `Config.Resolve` with a
|
||||
catalog. The existing runner's resolver requires every explicit step to have at
|
||||
least one artifact lane (`internal/framework/pipeline/profile.go`,
|
||||
`ResolvePipeline`). The parent is an ordinary executable step, not an excluded
|
||||
template. The fixture therefore cannot be used as a resolved pipeline, despite
|
||||
the positive test and the reference's unqualified mention of step-record
|
||||
inheritance.
|
||||
|
||||
Giving the parent a real artifact lane is not a simple repair to the fixture:
|
||||
native inheritance recursively copies that named lane into the child, while
|
||||
Notarius requires lane identifiers to be unique across steps. Adding a new
|
||||
child-specific lane does not remove the inherited one. Pipeline-level inheritance
|
||||
with step upsert is a different operation and remains supported and tested.
|
||||
|
||||
Offline reproduction through the current binary:
|
||||
|
||||
- A production-module equivalent of the test fixture loads for effective
|
||||
inspection, but `config validate --pipeline session` fails because the parent
|
||||
step must declare an artifact lane.
|
||||
- A parent with `parent-spells` and a child declaring `child-spells` fails domain
|
||||
validation because inherited `parent-spells` occurs in both steps.
|
||||
- A native identity declaration on an extraction validator list, with
|
||||
`generic/valid_json_schema` inheriting from `generic/valid_json` through
|
||||
`extends: {module: generic/valid_json}`, passes production pipeline validation.
|
||||
Generic identified-record inheritance is therefore usable; the gap is the
|
||||
selected positive step fixture and its implied runtime applicability.
|
||||
|
||||
Required changes:
|
||||
|
||||
- Replace or reframe the positive step fixture. Cover a genuinely executable
|
||||
identified-record use case in a compatible collection and verify it through
|
||||
`Config.Resolve` with the appropriate catalog or the equivalent public CLI
|
||||
validation path. Assert a meaningful inherited value, not only successful load.
|
||||
- Make the step-specific constraints clear alongside CK-1's syntax correction.
|
||||
Do not present the reference-only parent fixture as a runnable step template.
|
||||
Preserve the distinction between pipeline inheritance/upsert and inheritance
|
||||
between records of one final sequence.
|
||||
- Preserve the existing runtime constraints. This finding does not authorize
|
||||
template-only steps, implicit parent removal, lane renaming, or weaker lane-ID
|
||||
uniqueness. A separate product decision would be needed for such features.
|
||||
|
||||
Acceptance: positive inheritance coverage reaches the actual configuration
|
||||
consumer, and operator guidance distinguishes native composition from executable
|
||||
pipeline validity. The complete D&D example, generated-reference validation, and
|
||||
ordinary pipeline inheritance continue to behave unchanged. No production fix
|
||||
is indicated by the current evidence.
|
||||
|
||||
### Integration Audit Validation
|
||||
|
||||
- Reviewed the staged changes against configuration conversion, pipeline
|
||||
resolution/reference materialization, PromptKit construction/inspection,
|
||||
checkpoint identity, and CLI debug/output consumers.
|
||||
- `GOTOOLCHAIN=go1.27.0 GOWORK=off go test ./internal/core/config ./internal/cli ./internal/framework/llm ./internal/framework/pipeline ./internal/modules/integration`
|
||||
passed. This includes the maintained complete-example run, generated-reference
|
||||
handoffs, command overrides, selected-path debug provenance, and profile reports.
|
||||
- Temporary CLI fixtures outside the repository reproduced both step-inheritance
|
||||
failures and verified the compatible validator-record alternative. An additional
|
||||
author-identified validator list with whitespace-normalized module names also
|
||||
passed pipeline validation.
|
||||
- The full-suite, vet, race, tidy, and build results from the preceding review
|
||||
remain applicable to the unchanged implementation. No live provider call or
|
||||
production-quality evaluation was performed.
|
||||
|
||||
## ConfigKit Algorithmic Audit
|
||||
|
||||
Reviewed on 2026-11-18 against `b396581`. Production code remains identical to
|
||||
`c9744ad`. This pass examines the 11 stages for algorithmic correctness and
|
||||
avoidable scaling costs; it leaves the explicitly selected native composition,
|
||||
inheritance, discovery, and ownership algorithms in place. CK-1 through CK-3
|
||||
retain their earlier scope and status.
|
||||
|
||||
### Finding CK-4 — Memoize Source Directories During Path Normalization
|
||||
|
||||
Priority: P3. Category: efficiency/scalability opportunity. Status: complete.
|
||||
|
||||
Completed 2026-11-18: source-directory results, including missing/non-file
|
||||
results, are memoized by source ID in load-local state. Main-directory setup
|
||||
shares the lookup. Cache-sharing/isolation and existing path-origin tests pass;
|
||||
the full offline suite, vet, race, and tidy checks pass. Path policy is unchanged.
|
||||
Affected stages: 2–3; exposed by adoption of richer ConfigKit source metadata.
|
||||
|
||||
`internal/core/config/document_paths.go:144–176`, `documentPathBase`, calls
|
||||
`resolution.Source(sourceID)` for each file-authored relative path. Only the
|
||||
source's `Path` is needed to calculate its directory. The same source is queried
|
||||
again for every reference or destination it supplies.
|
||||
|
||||
In ConfigKit v1.2.0, `Source` returns a detached record that includes
|
||||
`EmptyImportSelections`: one record for each completed optional import declaration
|
||||
that selected no source. The pinned implementation clones these records and
|
||||
their paths on each query:
|
||||
|
||||
- `lifecycle.go:287–290`: public resolution-source lookup and conversion;
|
||||
- `internal/engine/load_metadata.go:47–52`: indexed lookup followed by a detached copy;
|
||||
- `internal/engine/records.go:333–345`: copying of the empty-selection evidence;
|
||||
- `conversion.go:45–66`: conversion of that evidence to the public record.
|
||||
|
||||
The older v0.5.0 source record did not contain this variable-sized evidence.
|
||||
The per-field lookup pattern predates the upgrade, but its snapshot cost now
|
||||
depends on metadata unrelated to the particular path being normalized. The
|
||||
source-ID lookup itself is indexed; the repeated copying is the avoidable work.
|
||||
|
||||
Complexity, disregarding path-string lengths:
|
||||
|
||||
- Let `R` be the number of relative fields supplied by one source and `E` its
|
||||
number of empty optional-import selections. Repeated source lookup contributes
|
||||
`O(R * (1 + E))` time and cumulative allocation volume. With `R` and `E` growing
|
||||
together, this component is quadratic in their combined count.
|
||||
- A load-local cache of source ID to its directory/lookup result reduces this
|
||||
component to `O(R + 1 + E)` for one source. Across visited sources, the bound is
|
||||
`O(R + U + sum(E_i))`, with `O(U)` small cached entries for `U` source IDs.
|
||||
- The cache should retain only the needed path-derived result, not every full
|
||||
source snapshot. One-time snapshotting for inspection and main-source selection
|
||||
can remain unchanged.
|
||||
|
||||
Recommended refactoring:
|
||||
|
||||
- Memoize the source-path/directory lookup within `documentLoadState`, scoped to
|
||||
one load and its resolution callback. Keep per-field `EntryInfo` queries so
|
||||
each surviving declaration still chooses its own source correctly.
|
||||
- Preserve CLI-invocation-relative, default-main-relative, imported/inherited,
|
||||
missing-source/non-file fallback, absolute-path, and empty-cache behavior.
|
||||
Memoization should reuse the native immutable source evidence without changing
|
||||
source acquisition or application path policy.
|
||||
- Reuse the existing path-origin and ownership tests. Verify the lookup is shared
|
||||
across paths from one source and remains distinct across sources; no elapsed-time
|
||||
assertion, real-world benchmark, new input limit, or release gate is warranted.
|
||||
|
||||
Acceptance: paths from the same source no longer repeatedly clone its unrelated
|
||||
import-selection evidence. Runtime paths, inspection results, and load isolation
|
||||
remain unchanged. This is a bounded optimization opportunity, not a correctness
|
||||
failure or a claim that ordinary inference runs will become materially faster.
|
||||
For sources with no empty selections, the current lookup cost is already small.
|
||||
|
||||
### Stage-By-Stage Algorithmic Assessment
|
||||
|
||||
| Stage | Assessment |
|
||||
| --- | --- |
|
||||
| 1 — Dependencies/toolchain | The mixed released graph is an approved choice; no new Notarius runtime algorithm was introduced here. |
|
||||
| 2 — API/handoff | LoadSource is a single delegation. MainSourcePath makes one source-metadata snapshot and scan, linear in that snapshot's size, rather than repeating discovery. CK-4 concerns repeated callback lookups, not this one-time accessor. |
|
||||
| 3 — Normalization/origins | Local passes visit each contained pipeline, step, lane, validator, and reference a bounded number of times. Deterministic key sorting costs `O(k log k)` per map. CK-4 identifies a hidden multiplicative snapshot cost inside those traversals. |
|
||||
| 4 — Collections | Identity registration delegates to the selected native algorithms. No application-side step matcher, concatenation loop, or quadratic merge was added. |
|
||||
| 5 — Fixtures | Mechanical fixture migration introduces no production algorithm. Previously recorded correctness/coverage findings remain separate. |
|
||||
| 6 — CLI discovery | Source selection has a fixed number of local branches and native preset descriptions; manual probes were removed. Selected-source reporting is performed once. |
|
||||
| 7 — Discovery/inspection coverage | The new tests exercise bounded cases; reports delegate to retained inspection. No extra load or source search was added for provenance. |
|
||||
| 8 — Examples | The extra fragment uses native dependency ordering and does not add application composition machinery. |
|
||||
| 9 — Operator docs | No runtime algorithm introduced. CK-1 and CK-2 already cover the relevant prose inaccuracies. |
|
||||
| 10 — Internals/notices | No runtime algorithm introduced or new dependency-graph translation added. |
|
||||
| 11 — Final verification | No production algorithm introduced; existing tests support correctness but do not establish complexity bounds. |
|
||||
|
||||
### Algorithmic Audit Evidence And Limits
|
||||
|
||||
- Inspected the production diff and traced traversal, original-path remapping,
|
||||
recording, source lookup, and CLI handoff helpers through the code graph.
|
||||
Nested collection loops traverse separate children rather than repeatedly
|
||||
scanning one global collection. Original-path remapping is bypassed during the
|
||||
pre-move path pass; its later worker-presence lookup has a fixed schema path.
|
||||
- Inspected the exact ConfigKit v1.2.0 source for snapshot ownership costs. Its
|
||||
record aggregation uses indexed reason/dependency sets, so repeated ancestor
|
||||
recording was not misclassified as a quadratic scan.
|
||||
- An offline temporary Go-overlay test verified that a single declaring-source
|
||||
snapshot contains four empty optional-import records while multiple relative
|
||||
reference paths normalize correctly. The probe passed; its files remain outside
|
||||
the repository. No production code or repository tests were modified.
|
||||
- Complexity conclusions come from source/data-flow analysis. No production
|
||||
inference, timing benchmark, or real-world performance measurement was used.
|
||||
Existing validation results remain applicable to the unchanged implementation.
|
||||
|
||||
No additional ordinary correctness bug was identified in this pass.
|
||||
Reference in New Issue
Block a user