Update ConfigKit adoption plan for version 0.3.0

docs/roadmap/configkit.md

@@ -7,27 +7,26 @@ default application, and configuration-inspection machinery with ConfigKit,
 while preserving Notarius ownership of pipeline semantics, module catalogs,
 runtime resolution, and invocation behavior.
 
-This roadmap is based on ConfigKit v0.2.0, the current stable release in the
-local `../ConfigKit` checkout. ConfigKit's maintained consumer guide includes a
-Notarius-shaped example, and its complete test suite passes locally. The
-dependency starts at v0.2.0; completing source-aware normalization requires a
-reviewed release with the extension below. Do not follow an unreviewed branch
-tip. Ordered implementation work belongs in
+This roadmap targets ConfigKit v0.3.0. Its released source-origin APIs support
+source-aware normalization within one load, removing the prior upstream
+dependency gate. Ordered implementation work belongs in
 [the implementation plan](implementation.md).
 
-### Source Metadata Dependency
+### Released Source Metadata Support
 
-Review for implementation identified an API gap in v0.2.0: `Resolution`
-exposes input presence and change recording, but not declaration origins or
-source paths. Those are available only on the completed `Result`, whose
-effective and explanation snapshots are already frozen. The target of
-recording declaration-relative path normalization in those snapshots therefore
-requires an upstream extension. The selected approach is to request source
-origins and canonical source records during resolution, then adopt a reviewed
-release providing that API. The implementation plan records the dependency
-gate. Resolving paths only after loading with a separate inspection report was
-considered but not selected; the agreed effective/explanation contract remains
-the target. ConfigKit v0.2.0 alone is insufficient for that part of the target.
+Use `Resolution.InputInfo(path) (FieldInfo, bool)` to query the fixed decoded
+entry state, and `Resolution.Source(id) (SourceInfo, bool)` to retrieve an
+already-acquired source's canonical file path. These callback-scoped queries
+return detached records and preserve original input attribution despite
+consumer normalization or map-key moves. Notarius records resolved values
+through the existing normalization API before ConfigKit freezes inspection
+output; no post-load path conversion or second load is needed.
+
+The v0.3.0 public-facade refactor preserves consumer signatures and introduces
+no additional migration. Use only the root public package. Go 1.25 remains
+supported; the private YAML v4 prerelease dependency is unchanged. ConfigKit's
+macOS support is now best-effort, consistent with Notarius's platform policy.
+No application platform expansion or new release gate is required.
 
 ## Motivation
 
@@ -119,7 +118,7 @@ requirements defined by the architecture and current integration contracts.
 - the meaning and validation of every Notarius field;
 - pipeline, module, validator, artifact, and reference catalogs;
 - conversion from configuration-facing values to runtime pipeline types;
-- source-relative interpretation of configured external reference paths;
+- source-relative interpretation of configured filesystem paths;
 - run-time selectors and actions such as lane selection, input, resume,
   recomputation, session identity, and CLI reference changes;
 - PromptKit profile discovery and validation; and
@@ -142,7 +141,7 @@ Use the following root declaration:
 version: 5
 ```
 
-ConfigKit v0.2.0 accepts string or strict decimal-integer input at the exact
+ConfigKit v0.3.0 accepts string or strict decimal-integer input at the exact
 path selected by its `VersionRule`. It passes the original spelling to the
 application checker and can decode an accepted integer into a string-backed Go
 field. This narrow exception lets Notarius retain its existing numeric YAML
@@ -295,20 +294,38 @@ to Notarius input, reference, output, cache, debug, or PromptKit profile paths.
 
 ### Paths And Source Ownership
 
-Resolve relative external reference paths and `promptkit.profile_file` and
-`promptkit.profile_dir` relative to the file that supplied the surviving value.
-This deliberately changes PromptKit profile-source paths from their current
-working-directory convention in version 5. Absolute paths remain absolute.
-Keep output, cache, and debug relative-directory semantics unchanged; they are
-runtime destinations rather than files bundled with configuration fragments.
+Resolve every nonempty relative application filesystem path authored in
+configuration against the canonical directory of the file supplying the
+surviving value. This includes external references, `promptkit.profile_file`,
+`promptkit.profile_dir`, and output, cache, and debug directories. Absolute
+paths remain unchanged. This deliberately changes configured PromptKit sources
+and runtime destinations from working-directory-relative behavior in version 5.
 
-Use ConfigKit's source metadata to identify each surviving declaration's
-origin, including profile replacements and values inherited from the base.
-Record path normalization so effective output and explanation reflect the
-paths used at runtime. Preserve attribution when identifier normalization
-renames an enclosing map key. Do not resolve overwritten or removed path
-values or infer source ownership from diagnostic display labels. Explicit CLI
-paths retain their working-directory interpretation.
+File-authored profile replacements use the profile file's directory, including
+equal-valued replacements. Inherited values keep their base-file origin.
+Built-in relative defaults have no declaring file and use the canonical main
+configuration directory. Explicit CLI-relative paths use the invocation's
+working directory, including output/debug overrides submitted through ConfigKit.
+CLI references remain invocation-owned. Empty optional cache paths keep their
+existing disabled/automatic meaning; do not turn an empty path into a directory.
+
+Use `InputInfo` at original scalar paths and `Source` for their source IDs,
+not composite parent origins or diagnostic display labels. Preserve original
+path mappings when identifiers are normalized. Record normalization so runtime,
+effective output, and explanation agree; do not resolve overwritten values.
+Canonical target-file directories, not symlink alias directories, supply bases.
+
+Notarius's file-backed loader must supply the canonical main directory and the
+invocation directory where needed. If a nonempty relative value unexpectedly
+lacks the provenance needed to choose its base, report a safe field diagnostic
+and fail loading rather than silently choose a different directory. This is a
+correctness failure, not an added restriction on operators' valid paths. Do not
+copy the upstream example's optional warning-and-leave-relative fallback.
+
+Application paths may be absolute or contain `../`; do not add confinement,
+target-existence checks, or new symlink restrictions during normalization.
+ConfigKit's own import and profile-source rules remain unchanged. Module-owned
+dynamic options are not automatically interpreted as filesystem paths.
 
 ## Discovery, Precedence, And Overrides
 
@@ -422,8 +439,8 @@ configuration or a new durable JSON API. There is no unredacted mode.
 
 The implementation must address the following coherent work areas:
 
-- add and pin a reviewed `gitea.maximumdirect.net/eric/ConfigKit` release with
-  v0.2.0's semantics and the required source-origin API;
+- pin `gitea.maximumdirect.net/eric/ConfigKit v0.3.0` and use its public
+  source-origin APIs;
 - introduce the version 5 typed document and its ConfigKit definition;
 - replace `LoadFileConfig`, custom `UnmarshalYAML` implementations, manual
   strict-parser checks, presence flags, `ApplyFileConfig`, and redundant
@@ -434,7 +451,7 @@ The implementation must address the following coherent work areas:
   discovery;
 - enable ConfigKit imports and configuration profiles, wire `--config-profile`
   through all configuration-loading commands, and retain declaration origins
-  for relative file paths;
+  for configured filesystem paths;
 - retire field-level environment overlays while retaining `NOTARIUS_CONFIG`;
 - classify current run flags so only true configuration overrides use
   ConfigKit override records and invocation-only state remains outside the
@@ -458,8 +475,10 @@ migration section with a concise version 4-to-5 migration guide covering:
 - expanding scalar module bindings into `{module: ...}` objects;
 - expanding scalar external references into `{path: ...}` objects;
 - moving lane-level reference aliases to `extract.references`;
-- resolving configured PromptKit profile-source paths from their declaring
-  file instead of the working directory;
+- resolving configured PromptKit profile-source and output/cache/debug paths
+  from their declaring file instead of the working directory, and built-in
+  relative defaults from the main configuration directory; CLI-relative paths
+  retain their invocation-directory base;
 - using imports for whole pipeline definitions and configuration profiles for
   overlays, including complete replacement of step sequences;
 - replacing retired operational environment overrides with YAML or supported
@@ -517,9 +536,10 @@ Required Notarius coverage includes:
   and profile precedence through the real ConfigKit loader;
 - profile sequence replacement and explicit clearing, so Notarius does not
   accidentally append or merge ordered steps;
-- relative reference and PromptKit profile-source paths from root files,
-  imported fragments, and overlays, including an unchanged inherited value,
-  a replaced value, and an enclosing normalized identifier;
+- relative references, PromptKit sources, and destination paths from root files,
+  imported fragments, and overlays, including inherited and equal-valued replaced
+  values, normalized enclosing identifiers, default bases, CLI bases, and empty
+  optional cache settings;
 - matching configuration-profile selection across execution, validation,
   pipeline listing, effective output, and explanation, without provider calls;
 - checked dynamic integer conversion at each production module option boundary;
@@ -572,9 +592,8 @@ profile validation, as documented today; no live provider call is required.
 
 ## Acceptance Criteria
 
-- All configuration-loading commands use a pinned ConfigKit release providing
-  the required source-origin API, building on v0.2.0, and no production code
-  directly imports a YAML parser.
+- All configuration-loading commands use ConfigKit v0.3.0 through its public
+  package, and no production code directly imports a YAML parser.
 - Version 5 is the only accepted file contract, documents `version: 5` as its
   canonical spelling, and has one canonical object representation for module
   bindings and references.
@@ -592,9 +611,9 @@ profile validation, as documented today; no live provider call is required.
 - Imports compose whole pipeline definitions and selected configuration
   profiles apply ConfigKit's documented overlay semantics consistently across
   all configuration-loading commands.
-- Relative external references and PromptKit profile-source paths use the
-  surviving declaration's source directory, and safe inspection agrees with
-  the paths used at runtime.
+- Configured relative filesystem paths use the surviving declaration's canonical
+  directory; built-in defaults use the main configuration directory and CLI
+  values use the invocation directory. Safe inspection agrees with runtime.
 - The resolved pipeline remains detached, reference content remains excluded
   from ordinary summaries, and its identity changes under the same semantic
   conditions as before.