Retire the completed ConfigKit upgrade plans

This commit is contained in:
2026-11-18 14:31:30 +00:00
parent 76364a7b7e
commit 65b8e8f0a2
4 changed files with 1 additions and 1373 deletions

View File

@@ -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.

View File

@@ -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.

View File

@@ -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

View File

@@ -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.