Plan reusable PromptKit CLI flag collections

docs/roadmap/promptkit-v0.19.0.md

@@ -154,12 +154,32 @@ snapshot a redacted configuration report or a transferable execution handle.
 Expose the upstream snapshot evidence without implying later execution uses
 that exact snapshot or will succeed.
 
-Share CLI binding implementation where it reduces duplication between smoke,
-validation, and preview. Preserve native explicit zero/empty values and
-whole-map replacement semantics. Keep parsing in CommandKit and domain validity
+Provide public, reusable typed execution-flag collections in `ckprompt`, defined
+once and used by smoke, validation, preview, and application-owned commands.
+The collections standardize flag names, help, parsing, completion hints,
+supplied-value tracking, and binding into native PromptKit request fields.
+Applications retain their own input structs, request construction, engine
+acquisition, execution, and outcomes. Reusing CLI declarations is within
+CommandKit's ownership boundary; it does not introduce runtime convenience APIs.
+
+Use the existing core `CommandSpec[I].Flags`, typed flag constructors, and
+`Supplied[T]`. A generic collection factory can accept destination accessors
+and return ordinary `[]commandkit.Flag[I]`. Direct binding is sufficient for
+ordinary use; existing [CaptureFlags and FlagValues.ApplyTo](../../flag_values.go)
+support deferred application or multiple destinations where needed. No core
+change or new core collection abstraction is currently required. Exact exported
+names and accessor signatures remain implementation design choices.
+
+Keep execution-target overrides and the request-level transient retry field
+distinct even when one convenient collection includes both. Preserve omission
+instead of imposing shared defaults: ordinary execution and smoke diagnostics
+have different native retry defaults. Preserve native explicit zero/empty
+values and whole-map replacement semantics. Support deliberate subsets for
+actual command needs while retaining common flag names and meanings, using a
+proportionate composition API. Keep parsing in CommandKit and domain validity
 in PromptKit. Existing application builders remain usable; resolve override
 precedence and the remaining request controls under OD-2 before documenting new
-public behavior. These helpers serve standard CLI commands only.
+public behavior.
 
 ### Namespace selection
 
@@ -262,8 +282,10 @@ errors remain errors even if an override would replace the affected value.
    candidate note and affected canonical dependency/compatibility guidance.
    No core Go-minimum increase follows from this adoption.
 3. **Implement request inspection and selection.** Add preview, applicable
-   override flags, provider-parameter input, and namespace selectors. Reuse the
-   standard suite's lifecycle and preserve existing application adapter seams.
+   override flags, provider-parameter input, and namespace selectors. Implement
+   public `ckprompt` execution-flag collections on existing core bindings and
+   reuse them in the standard commands. Reuse the standard suite's lifecycle
+   and preserve existing application adapter seams.
 4. **Implement shared configuration inspection.** Add metadata discovery and
    explicitness, detailed diff presentation, source evidence on failure, and
    structured diagnostics in `ckconfig`; wire native PromptKit facets through
@@ -304,6 +326,11 @@ Default tests remain offline and independent of real credentials.
 - [ ] New flags preserve selected omission/empty/zero semantics, parse malformed
   inputs through the existing usage path, and do not leak state between runs.
   Numeric decoding of provider JSON matches the selected strategy in OD-2.
+- [ ] The same public execution-flag collection works in a standard subcommand
+  and an application-owned command with its own typed input. Parsing, presence,
+  metadata, and selected subsets remain consistent; omitted retry values retain
+  the applicable native defaults. Application execution behavior remains outside
+  the collection.
 - [ ] Namespace defaults, explicit clearing, qualified selections, and catalog
   filters are forwarded according to the selected design.
 - [ ] Metadata discovery distinguishes effective and historical paths, retains
@@ -332,7 +359,8 @@ Default tests remain offline and independent of real credentials.
   do not start acquisition. New operation/flag metadata and static completion
   match the implemented surface.
 - [ ] Maintained consumer examples demonstrate the selected CLI tasks and the
-  configuration failure workflow with deterministic local evidence.
+  configuration failure workflow with deterministic local evidence, including
+  collection reuse by an application-owned command.
 - [ ] Canonical documentation, module release notes, and roadmap links agree
   with the implemented boundary. Open decisions are resolved or deliberately
   superseded before the corresponding behavior is claimed complete.
@@ -390,6 +418,11 @@ stay entirely within CLI ownership; select vocabulary and formats before coding.
 
 ### OD-2: Request controls and provider-parameter grammar
 
+**Agreed design direction:** execution flags are public reusable CLI collections
+owned by `ckprompt`, available to standard and application-owned commands using
+existing core APIs. The remaining decisions here concern request controls and
+grammar, not whether application commands may reuse the collections.
+
 **Recommendation:** give validation and preview the applicable execution flags
 already on smoke tests, and add a singleton `--extra-params JSON` object option
 to all three. Use native whole-map replacement, including native behavior for