2026-11-17 20:35:04 +00:00
|
|
|
|
# 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")
|
2026-10-04 11:38:01 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:57:31 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 1 — Select The Mixed Dependency Graph And Toolchain
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:39:48 +00:00
|
|
|
|
**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.
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: establish the approved build inputs without migrating PromptKit.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect `go.mod`, `go.sum`, pinned ConfigKit/PromptKit module files, the v1.2.0
|
|
|
|
|
|
consumer migration guide, and `docs/release.md`.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: `GOTOOLCHAIN=go1.27.0 GOWORK=off go version`, selected module inspection,
|
|
|
|
|
|
and a compilation attempt. Network/dependency preparation precedes offline tests.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: dependency/toolchain preparation only.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 2 — Migrate Application APIs And Separate Old PromptKit Types
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:42:25 +00:00
|
|
|
|
**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.
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: move the application loader and CLI to v1 APIs.
|
2026-10-04 12:15:26 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-10-04 11:38:01 +00:00
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: native build to a `mktemp -d` location; focused compile/test attempts for
|
|
|
|
|
|
`./internal/core/config ./internal/cli ./internal/framework/llm`; diff review.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: API/handoff migration; no discovery implementation or broad fixtures.
|
2026-10-03 17:55:58 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 3 — Simplify Recorded Normalization And Preserve Source Bases
|
2026-10-04 12:29:55 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: use v1.1 field-level auditing instead of old blanket sequence coverage.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect document_normalizer.go, document_paths.go, pipeline_document.go,
|
|
|
|
|
|
reference normalization helpers, and existing path/inheritance tests.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: one resolution/provenance boundary.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 4 — Register Steps And Exercise Native Collection Semantics
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: implement the accepted step identity and composition policy.
|
2026-10-04 12:46:23 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect documentDefinition, pipeline step validation/conversion, ConfigKit's
|
|
|
|
|
|
pinned sequence/placement contract, and inheritance tests.
|
2026-10-03 17:58:48 +00:00
|
|
|
|
|
2026-10-04 11:38:01 +00:00
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: native composition produces the intended typed pipeline and existing
|
|
|
|
|
|
domain rules still apply. Default upsert and explicit replace differ as documented.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: config collection/inheritance tests and focused framework resolution tests.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: one definition registration and its focused behavior coverage.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 5 — Migrate Application Fixtures And Restore Configuration Coverage
|
2026-10-04 12:59:29 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: translate existing tests to the selected source contract.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect config document/operational/loaded/paths/inheritance tests and CLI
|
|
|
|
|
|
ConfigKit/command/production tests. Discover literals and helpers by consumer.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: existing application configuration coverage exercises v1.2.0 with
|
|
|
|
|
|
intentional semantic changes documented in tests; LLM fixtures still use old types.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: `GOWORK=off go test ./internal/core/config ./internal/framework/llm` plus
|
|
|
|
|
|
CLI compile/tests, noting discovery assertions assigned to Stages 6–7.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: mechanical fixture migration; avoid unrelated production refactoring.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 6 — Delegate CLI Discovery And Publish The Actual Selected File
|
2026-10-04 13:08:56 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: replace filesystem probing with the settled native source selection.
|
2026-10-03 18:03:40 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect loadConfigKit, discoverConfigPath/requireConfigFile, command dispatch,
|
|
|
|
|
|
Options.LookupEnv, and invocation/debug use of loadedConfigPath.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-10-04 11:38:01 +00:00
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: no manual file search precedes ConfigKit; every config-consuming
|
|
|
|
|
|
command uses the same selected source and its retained provenance.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: focused CLI load/discovery/report tests and native build.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: shared CLI loading boundary, not the full discovery test matrix.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 7 — Verify Discovery, Inspection, And Failure Semantics
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: protect the new operator contract with bounded offline coverage.
|
2026-10-04 13:15:40 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: selection precedence and terminal failures are observable through
|
|
|
|
|
|
commands without a second acquisition pass or host-dependent fixtures.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: `GOWORK=off go test ./internal/core/config ./internal/cli ./internal/framework/llm`.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: discovery and cross-boundary behavioral verification.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 8 — Maintain Runnable Native Composition Examples
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: demonstrate the approved features in the existing two top-level examples.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Inspect examples/dnd-complete.config.yml, pipelines/dnd-session.yml, development
|
|
|
|
|
|
overlay, profile file, and internal/cli/example_contract_test.go.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 18:08:07 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: maintained configurations load natively and demonstrate composed steps
|
|
|
|
|
|
plus inheritance with no duplicated complete pipeline or altered D&D execution policy.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: existing CLI example tests and module-integration tests; credential-free
|
|
|
|
|
|
CLI validation of minimal, complete, and development selections.
|
2026-10-04 13:26:54 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: one supporting fragment and existing example coverage.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 9 — Update Operator And Consumer Documentation
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: document implemented native behavior and migration in canonical homes.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: operator guidance explains real new semantics and intentional migration
|
|
|
|
|
|
without introducing extra import restrictions or promising unchanged composition.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: relevant example tests, link/command review, and `git diff --check`.
|
2026-10-04 13:47:00 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: public references and concise consumer/workflow adjustments.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 10 — Update Integration References And Attribution
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: make ownership and the temporary mixed graph accurately documented.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Acceptance: current docs and factual notices match the selected mixed graph;
|
|
|
|
|
|
historical ADRs/releases remain untouched. No policy or license grant is expanded.
|
2026-10-04 13:54:17 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Checks: selected module inspection, pinned/local link and notice review, whitespace
|
|
|
|
|
|
check. Reuse unchanged example validation rather than adding documentation snapshots.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: focused internal/integration docs and dependency notices.
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
## Stage 11 — Verify The Entire Target And Finish The Sprint
|
2026-10-04 11:38:01 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Goal: prove all feature-roadmap acceptance on the completed implementation.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
Work:
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
- 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:
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
|
GOWORK=off go test ./...
|
|
|
|
|
|
GOWORK=off go vet ./...
|
|
|
|
|
|
GOWORK=off go mod tidy -diff
|
2026-11-17 20:35:04 +00:00
|
|
|
|
GOWORK=off go list -m go.maximumdirect.net/configkit gitea.maximumdirect.net/eric/ConfigKit gitea.maximumdirect.net/eric/promptkit go.yaml.in/yaml/v4
|
2026-10-03 17:33:13 +00:00
|
|
|
|
git diff --check
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|
2026-10-04 14:17:30 +00:00
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
Prompt size: final evidence review and small cleanup; significant newly discovered
|
|
|
|
|
|
scope requires an explicit decision rather than silently narrowing acceptance.
|
2026-10-03 17:33:13 +00:00
|
|
|
|
|
|
|
|
|
|
## Open Questions
|
|
|
|
|
|
|
2026-11-17 20:35:04 +00:00
|
|
|
|
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.
|