diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md deleted file mode 100644 index f3698cbb..00000000 --- a/docs/roadmap/configkit.md +++ /dev/null @@ -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//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. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 42e8acfe..00000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -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:` 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. diff --git a/docs/roadmap/promptkit.md b/docs/roadmap/promptkit.md index 74fe6e47..f18ebce7 100644 --- a/docs/roadmap/promptkit.md +++ b/docs/roadmap/promptkit.md @@ -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 diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index 4b3cd619..00000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -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.