Settle PromptKit requirements inspection roadmap

docs/roadmap/requirements.md

@@ -1,9 +1,8 @@
 # PromptKit requirements inspection
 
-Status: proposed feature roadmap; no implementation in this document. The
+Status: accepted feature roadmap; implementation has not started. Command
-recommended command placement reflects the user's preference. The remaining
+placement, public API, caller-variable syntax, and initial presentation are
-API and presentation recommendations are identified under
+settled.
-[Open Decisions](#open-decisions).
 
 ## Purpose and authority
 
@@ -22,13 +21,15 @@ The [architecture policy](../policy/architecture.md),
 [outcome decision](../adr/0005-invocation-outcomes.md),
 [module boundary decision](../adr/0010-optional-integration-modules.md), and
 [declaration and input decision](../adr/0011-captured-declarations-and-installation.md)
-control this work. This roadmap proposes an additional PromptKit operation;
+control this work. This roadmap selects an additional PromptKit operation within
-ADR 0004 does not already specify its command spelling.
+the established architecture. ADR 0004 remains unchanged; the command spelling
+and report belong in this roadmap until their canonical documentation is updated
+with implementation.
 
 PromptKit's adopted public
 [requirements API](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/requirements.go)
 is the authority for discovery semantics. Descriptions below explain how
-CommandKit would expose that API, rather than establishing a separate discovery
+CommandKit will expose that API, rather than establishing a separate discovery
 specification.
 
 ## Current baseline
@@ -67,7 +68,7 @@ Use the existing public facade and internal backend boundary.
 
 ## Target operator surface
 
-Recommended operation:
+Selected operation:
 
 ```sh
 app promptkit requirements show PROMPT_ID
@@ -75,26 +76,52 @@ app promptkit requirements show briefing --version 2 --profile editorial --var a
 app promptkit requirements show briefing --session-id session-42 --var note= --format yaml
 ```
 
-The operation displays requirements for one selected prompt context. It accepts
+The `requirements` resource namespace follows the resource-first pattern of
-the existing configuration selection flags (`--config` and repeatable
+`config show` and gives future requirements operations a location without
-`--overlay`) and the suite's application selectors. Its namespace already
+selecting them for this delivery.
-identifies PromptKit; an additional configuration `--scope` selector is not
-needed.
 
-| Proposed input | Meaning |
+The operation displays requirements for one selected prompt context. It accepts
+the existing singleton configuration selection flags (`--config` and
+`--overlay`) and the suite's application selectors. Repeated occurrences of
+either singleton use the last value; overlays do not accumulate. Its namespace
+already identifies PromptKit; an additional configuration `--scope` selector is
+not needed.
+
+| Input | Meaning |
 | --- | --- |
 | `PROMPT_ID` | One required prompt identifier, passed to PromptKit with its exact spelling. |
 | `--version VERSION` | An exact prompt version; omission uses PromptKit's native selection rule. |
 | `--profile PROFILE_ID` | A profile identity; omission uses the selected prompt's default under the native API. |
 | Repeatable `--var KEY=VALUE` | Caller-variable discovery context, including explicitly empty string values. |
 | `--session-id SESSION_ID` | Session context passed to PromptKit for its native normalization and discovery behavior. |
-| `--format yaml` | Explicit selection of the recommended initial report format, also the default. |
+| `--format yaml` | Explicit selection of the initial report format, also the default. |
 
 The existing grammar and binding contracts apply. CommandKit should not add
 independent prompt/profile lookup rules, infer a profile from the catalog, or
 reinterpret native session validity. Parse the new CLI representation, then
-delegate domain interpretation to PromptKit. The exact variable grammar and
+delegate domain interpretation to PromptKit.
-report format remain recommendations in the decisions below.
+
+### Caller-variable syntax
+
+Use repeatable `--var KEY=VALUE`, splitting each assignment at the first `=` and
+preserving the exact key and remaining value. A missing separator is a usage
+error. Repeated keys use the last supplied value, consistent with the existing
+singleton override convention. Every occurrence is parsed, so a later valid
+assignment does not erase an earlier malformed one.
+
+| Invocation fragment | Result |
+| --- | --- |
+| `--var note=` | Key `note` is supplied with an empty string value. |
+| `--var token=a=b` | Key `token` has value `a=b`. |
+| `--var =value` | The empty key has value `value`. |
+| `--var mode=brief --var mode=full` | Key `mode` has value `full`. |
+| `--var 'note=hello, world'` | Key `note` has value `hello, world`. |
+| `--var broken --var mode=full` | Usage error because `broken` has no separator. |
+
+Preserve whitespace and commas literally after shell processing. Do not normalize
+keys or impose an identifier whitelist beyond the native string-map contract.
+Variable-context files can be considered later if inline assignments prove
+insufficient; file acquisition and override precedence are outside this delivery.
 
 ## Native meaning and invocation outcomes
 
@@ -130,7 +157,7 @@ Apply the established outcomes to actual failures:
 
 The default adapter calls the native inspection API. It does not add request
 preparation, artifact loading, template rendering, execution, credential probes,
-or a separate readiness verdict. These are limits of the proposed standard
+or a separate readiness verdict. These are limits of the selected standard
 operation, not new restrictions on application loaders or custom callbacks.
 
 PromptKit does not return supplied variable values as a separate inventory of
@@ -141,11 +168,32 @@ in output.
 
 ## Target public integration and lifecycle
 
-Extend `Suite[I, S]` with an optional `InspectRequirements` callback returning
+Add this request type in ckprompt:
-`commandkit.Acquired[*promptkit.RequirementInspection]` and an error. It receives
+
-the invocation context, a requirements request, the selected application input
+```go
-`I`, and shared state `S`. The recommended request representation is described
+type RequirementsRequest struct {
-under OD-2.
+    Selection  ckconfig.Selection
+    Inspection promptkit.RequirementInspectionRequest
+}
+```
+
+Extend `Suite[I, S]` with this optional callback field:
+
+```go
+InspectRequirements func(
+    context.Context, RequirementsRequest, I, S,
+) (commandkit.Acquired[*promptkit.RequirementInspection], error)
+```
+
+The callback receives invocation context, configuration selection and native
+discovery context, selected application input `I`, and shared state `S`. Reusing
+the owning library's public request avoids duplicating its domain model and
+keeps forwarding and future adoption straightforward.
+
+Configuration and application-selector presence retain their existing contracts;
+variable presence is represented by exact map keys. Native version/profile/session
+string fields use their native empty-value semantics, so this representation
+does not distinguish omission from explicit empty for those fields.
 
 `FromEngine` supplies this callback using the same loader and diagnostics
 adaptation as its existing inspection callbacks, followed by
@@ -172,10 +220,12 @@ diagnostic ownership and buffered report delivery, including cancellation checks
 and incomplete-delivery reporting, without claiming rollback of written bytes or
 interruption of a blocking writer.
 
-## Recommended report
+## Initial report
 
-Use YAML only initially, with a CommandKit-owned report representation rather
+Use YAML only initially, defaulting to YAML and accepting `--format yaml`
-than serialization that relies on incidental Go field names. Proposed fields:
+explicitly. YAML expresses partial inventories, metadata presence, and structured
+issues readably and supports automation. Additional formats can follow operator
+needs. Define a CommandKit-owned report representation with these fields:
 
 | Report area | Fields |
 | --- | --- |
@@ -209,15 +259,50 @@ variables:
 issues: []
 ```
 
+For a prompt with the captured template
+`{{if .mode}}{{input "notes"}}{{end}}`, no input declarations, and profile
+`editorial`, omitting `mode` produces a useful partial inventory under the
+adopted native API. Its initial YAML presentation is illustrated here:
+
+```yaml
+prompt_id: briefing
+prompt_version: "2"
+profile_id: editorial
+complete: false
+inputs:
+  - name: notes
+    kind: conditional
+    declared: false
+    content_type: null
+    description: null
+    explanation: This reference is not known to be reached on every execution path.
+variables:
+  - name: mode
+    kind: required
+    supplied: false
+    explanation: ""
+issues:
+  - code: missing_variable
+    input_name: ""
+    variable_name: mode
+    description: A missing variable prevents selecting a dependency-bearing branch.
+```
+
+For that same prompt, supplying `--var mode=full` lets native discovery select
+the branch: `notes` becomes required, `mode` is supplied, discovery is complete,
+and the issues sequence is empty. Both successfully delivered inspections return
+status `0`. The human-readable explanation and description above illustrate the
+adopted upstream output; their wording remains upstream-owned.
+
 Structured discovery issues stay in this report. Engine acquisition diagnostics
 continue through the diagnostic stream. The implemented CLI reference will own
-the final schema; this example does not define PromptKit discovery behavior.
+the final schema; these examples do not define PromptKit discovery behavior.
 
 ## Work needed from the baseline
 
 ### Public contracts and adaptation
 
-Finalize the open API choices, extend the suite and its GoDoc, and adapt
+Add `RequirementsRequest`, extend the suite and its GoDoc, and adapt
 `FromEngine` through the existing acquisition path. Preserve native errors and
 diagnostics. Reuse ckconfig selection instead of adding parallel configuration
 loading or asking providers to construct a CommandKit-specific discovery model.
@@ -241,14 +326,16 @@ acquisition diagnostics and readiness claims.
 During implementation, add focused coverage using real native inspection where
 practical, together with boundary doubles for lifecycle and delivery failures.
 Cover independently enabled and disabled capabilities, help without acquisition,
-request forwarding, exact/empty variable presence, selected profile/version and
+request forwarding, the selected variable-parsing cases, selected profile/version
-session context, complete and partial inventories, structured issues, nullable
+and session context, complete and partial inventories, structured issues, nullable
 metadata, native error identity, and invocation isolation. Exercise acquisition
 diagnostics and writer failures through existing outcome paths.
 
-Extend the maintained composed consumer with a useful requirements example and
+Extend the maintained composed consumer with fixtures that demonstrate a partial
-fixtures. Validate the affected integration and composed example under the
+inventory and how supplying discovery context changes it. Show that both
-repository's existing module/workspace procedures. Reuse established core and
+successfully delivered inspections return status `0`. Validate the affected
+integration and composed example under the repository's existing module/workspace
+procedures. Reuse established core and
 configuration coverage; this feature does not justify new generic validation
 infrastructure, performance guarantees, or release gates.
 
@@ -256,11 +343,10 @@ infrastructure, performance guarantees, or release gates.
 
 When implementation lands, update ckprompt GoDoc, the CLI reference, consumer
 guidance, and relevant internal summaries under their existing ownership rules.
-Reconcile the deferred-work entry with this feature's actual status. Assess
+Reconcile the deferred-work entry with this feature's actual status. The new
-whether extending ADR 0004's recorded surface needs a focused new ADR; preserve
+operation fits the existing ownership and registration boundaries and requires
-accepted decision content under the documentation policy rather than silently
+no new ADR. Leave ADR 0004 unchanged. Command spelling and report/API details
-editing it. Report/API details that evolve within the existing architecture can
+belong with their canonical owners when implemented.
-remain with their canonical owners.
 
 Release documentation and module version selection follow the existing release
 procedure when a release is prepared. No upstream release, dependency bump,
@@ -279,70 +365,4 @@ readiness checker, artifact binding workflow, or additional analysis beyond the
 native API. Further capabilities can be considered for concrete needs; these
 scope boundaries do not prohibit future extensions.
 
-## Open Decisions
+The decisions needed for an implementation plan are settled.
-
-### OD-1: Command placement
-
-**Recommendation (user-selected):**
-`app promptkit requirements show PROMPT_ID`.
-This gives requirements an explicit resource namespace and follows the
-resource-first pattern of `config show`. Future requirements operations have a
-clear location without being selected by this roadmap.
-
-**Alternative:** `app promptkit show requirements PROMPT_ID`.
-This matches the existing `promptkit show prompt` and `show profile` layout and
-keeps display operations together. Requirements would sit beneath a verb,
-however, and later requirements verbs would need separate locations. The
-recommended shape accepts the small vocabulary difference within PromptKit in
-exchange for a coherent requirements resource.
-
-### OD-2: Public request representation
-
-**Recommendation:** introduce a small ckprompt request with
-`Selection ckconfig.Selection` and
-`Inspection promptkit.RequirementInspectionRequest`. This deliberately uses
-the owning library's public request for domain context, avoids duplicating its
-model, and makes forwarding and future adoption straightforward. Configuration
-and application-selector presence retain their existing contracts; variable
-presence is represented by exact map keys. Native version/profile/session string
-fields use their native empty-value semantics, so this representation does not
-distinguish omission from explicit empty for those fields.
-
-**Alternative:** define CommandKit-owned request fields, using
-`commandkit.Supplied[string]` for version, profile, and session ID, then translate
-to the native request in `FromEngine`. This resembles existing `PromptRequest`
-and lets custom providers distinguish omitted and explicitly empty flags.
-It requires another maintained domain-context representation and conversion,
-although native inspection currently treats those cases the same. Prefer it if
-that distinction is useful to an actual custom-provider contract.
-
-### OD-3: Caller-variable CLI representation
-
-**Recommendation:** repeatable `--var KEY=VALUE`, splitting at the first `=` and
-preserving the exact key and remaining value, including empty strings and
-additional `=` characters. A missing separator is a usage error. Repeated keys
-use the last supplied value, consistent with the suite's existing singleton
-override convention. Do not add key normalization or an identifier whitelist
-that the native caller map does not require. This is a small, transparent
-representation of the native string map.
-
-**Alternative:** accept a YAML variable-context file, potentially alongside
-explicit flag overrides. Files are convenient for large or repeatedly used
-contexts and reduce shell quoting. They add file acquisition, map/value
-validation, and precedence decisions to this feature. They are a viable later
-extension if inline variables prove insufficient; adding both now expands the
-initial delivery without an established consumer need.
-
-### OD-4: Initial report formats
-
-**Recommendation:** YAML only, defaulting to YAML and accepting explicit
-`--format yaml`, using the report representation above. YAML expresses partial
-inventories, metadata presence, and structured issues readably and supports
-automation. Existing catalog and comparison operations already use this format
-policy, so the new operation need not duplicate presentation logic.
-
-**Alternative:** text and YAML, with text as the default, matching existing
-named prompt/profile display. A tailored text summary could be easier to scan
-for large inventories. It requires an additional renderer and decisions about
-which evidence to retain in that summary. Add it if operator experience shows a
-clear benefit; the native structured result does not require it.