Clarify resource version policy and roadmap planning scope

This commit is contained in:
2026-11-21 04:09:32 +00:00
parent f80ec1c42c
commit bb8ec2c792

View File

@@ -201,9 +201,9 @@ appropriate nested location. Source-relative context follows the effective
contributing field, not the location of the application document or mount point.
ConfigKit-owned headers and directives retain their native semantics. The
application owns its main configuration specification; PromptKit's registration
must not replace that policy with its standalone document version rule.
Independent source-version policies are deferred as described below.
application owns its configuration version policy. PromptKit's registration
preserves that policy; PromptKit-specific resource version validation is removed
as described below.
An absent `promptkit` section contributes no application-supplied PromptKit
settings; selected bundled underlays can still contribute defaults during the
@@ -226,8 +226,7 @@ inspection, ok := result.InspectSubtree(configkit.Keys("promptkit"))
PromptKit's `InspectConfiguration()` forwards the view's capabilities without
loading another configuration or rebuilding history, redaction, or comparison.
Both application-owned loading and standalone construction use this reporting
path. This replaces the earlier inspection deferral; independent source-version
policies remain deferred.
path. This replaces the earlier inspection deferral.
The view is a reporting focus, not an isolation or access-control boundary.
Accept ConfigKit's native behavior:
@@ -261,28 +260,29 @@ claiming exclusive access to PromptKit information. Resource APIs continue to
select and describe logical prompts, profiles, and backends independently of
configuration-tree paths.
### Deferred Independent Source-Version Policies
### Resource Version Validation
Different application and component header policies within one load are outside
this initial addition. ConfigKit's existing shared-policy limitation remains.
Planning must document a supported
source/header arrangement using current semantics, including the consequence for
application and collection documents declaring different specification versions.
Do not imply those headers are independently checked, overwrite the application's
policy, preparse/strip headers, or perform a second load to simulate the deferred
capability. Standalone construction retains its applicable native version policy.
**Accepted:** this migration gives up PromptKit-specific validation of `version`
fields in resource documents, including collection, prompt, and profile
definitions. This is an intentional simplification with a small practical cost,
not an unresolved compatibility requirement or a prerequisite for an upstream
version-policy feature.
This remains outside both the accepted upstream addition and this migration;
neither typed lookup nor focused inspection provides independent version checks.
The application retains ownership of ConfigKit's version policy. ConfigKit-owned
headers and directives follow that policy and native composition semantics;
PromptKit adds no separate resource-version checks. Apply this resource decision
to both application-owned loading and standalone construction. Update examples
and migration guidance accordingly, without preparsing or stripping headers or
adding a second load.
## Guidance For Implementation Planning
### Validate The Pattern Against PromptKit
First confirm the final upstream lookup and inspection contracts and availability.
The ConfigKit agent exercised representative one-library and two-library prototypes using
existing public callbacks plus a limited top-level lookup shim. Those passed
checks for defaults, normalization, validation, identities, sensitive inspection,
The ConfigKit agent exercised representative one-library and two-library
prototypes using existing public callbacks plus a limited top-level lookup shim.
Those passed checks for defaults, normalization, validation, identities, sensitive inspection,
trusted secret access, and mounted resource lookup. They were not a production
`Value` implementation or a real PromptKit integration.
@@ -307,23 +307,22 @@ the standalone convenience path through the same rules. Focus on these checks:
mounting, inheritance, and overrides. Document mutation-before-handoff behavior;
no mutation-detection subsystem or ConfigKit deep-copy guarantee is required.
4. **Inspection facade and diagnostics.** Retain the native focused view and specify
any public signature changes needed to forward it. `Value` can succeed without
completed-load evidence; do not treat that as proof of a valid inspection view.
The proposed upstream method list does not explicitly include `Diagnostics`.
Resolve forwarding from the original result through PromptKit's consumer-owned
interface, or use an upstream view method if supplied. Preserve useful load
evidence without inventing component-specific diagnostic classification.
5. **CommandKit integration.** Coordinate migration of `ckprompt.ConfigScope` and
resource adapters. Its shared loader currently calls `InspectConfiguration()`
for sources and diagnostics even for resource commands; preserve those commands
and their diagnostics during migration. `ckconfig.View` currently accepts a
concrete `*configkit.Metadata`; forwarding that alone would expose unfiltered
path discovery. Use the view's focused enumeration or apply the selected scope
in the adapter. A PromptKit overview explanation must request `/promptkit`:
the native empty path still selects the whole application. Keep explicit query
paths native and document the broader contextual evidence and ancestor-diff
semantics. Preserve operator capabilities rather than promise unchanged method
signatures or rebuild ConfigKit behavior in CommandKit.
public signatures for its operations and load-diagnostic forwarding. Obtain
diagnostics from the original result through PromptKit's consumer-owned
interface, or use an upstream view method if supplied. Expose focused enumeration
alongside native metadata and query operations. A PromptKit overview explanation
selects `/promptkit`; the native empty path selects the whole application.
Document what the interfaces do: their inputs, operations, outputs, and errors,
and how registration, loading, and engine construction fit together. Keep this
guidance concrete; hypothetical misuse does not call for registration tracking,
another validation lifecycle, or defensive caveats.
CommandKit neutrally exposes upstream PromptKit APIs. Any adapter updates are
routine downstream adoption, not a constraint on PromptKit's public API or a
prerequisite for completing this migration. PromptKit's implementation plan covers
its own resource, inspection, and diagnostic capabilities; CommandKit owns how
those are presented through CLI commands.
Specify the concrete registration, settings, and constructor shapes, source-helper
adaptations, and migration examples after these checks. Identify any remaining
@@ -354,21 +353,20 @@ compatibility resolver.
inside `promptkit`.
- Engine independence from later caller mutation of settings, including nested
maps and slices; trusted lookup does not replace redacted inspection.
- Resource listings, resource reports, and load diagnostics through the migrated
CommandKit adapters; configuration output and overview explanations focused on
- Resource listings, resource reports, and load diagnostics through PromptKit's
public APIs; configuration output and overview explanations focused on
`/promptkit`, with native paths and redaction preserved.
- Focused discovery through the adapter despite unfiltered metadata; explicit
- Focused enumeration alongside unfiltered metadata; explicit
queries outside the focus and shared source/history context retain native behavior.
- Inspection remains frozen after settings mutation; absent, null, historical-only,
and added/removed sections follow upstream semantics. Sibling difference records
are excluded while ancestor differences remain; comparison works across different
application root types selecting the same scope.
The product direction, including focused inspection, is accepted. Actual PromptKit
integration, concrete public API shapes, diagnostic forwarding, CommandKit adapter
migration, and the supported shared header policy remain planning work. Strict
subtree isolation, a new comparison engine, and independent source-version policies
are not required by this design.
The product direction, including focused inspection and removal of resource-version
validation, is settled. No product decisions remain before implementation planning.
Concrete public API shapes, diagnostic forwarding, and verification of the actual
PromptKit integration are implementation-planning work.
## Further Candidates