commandkit/docs/roadmap/requirements.md

# PromptKit requirements inspection

Status: accepted feature roadmap; implementation has not started. Command
placement, public API, caller-variable syntax, and initial presentation are
settled.

The [implementation plan](implementation.md) owns the ordered delivery steps and
stage completion evidence.

## Purpose and authority

Expose PromptKit's prompt requirements inspection through the optional ckprompt
integration. An operator should be able to select a prompt, supply discovery
context, and inspect the resulting input and caller-variable inventory before
input artifacts exist.

The governing principle is: **CommandKit provides useful, consistent access to
capabilities owned elsewhere.** PromptKit owns requirement discovery and the
meaning of its results. CommandKit owns command vocabulary, registration,
selection, coordination, presentation, and invocation outcomes.

The [architecture policy](../policy/architecture.md),
[standard inspection decision](../adr/0004-standard-inspection-surface.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 selects an additional PromptKit operation within
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 will expose that API, rather than establishing a separate discovery
specification.

## Current baseline

Baseline: CommandKit commit
[`12b52b3`](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/12b52b3174545d22960c91c3a782a151ab813447).

| Area | Current implementation | Gap to target |
| --- | --- | --- |
| Dependencies | ckprompt already adopts PromptKit v0.14.0, ConfigKit v0.7.1, and YAML v4. Modules require Go 1.26.0. | No dependency or toolchain upgrade is needed for this capability. |
| Native capability | PromptKit exposes `Engine.InspectRequirements`, its request, and its structured result. | Adapt this existing public API. |
| Public integration | `Suite[I, S]` provides optional prompt/profile inspection and prompt/profile catalog callbacks. `FromEngine` supplies those four callbacks. | Add an independently optional requirements callback and its engine adapter. |
| Command assembly | `ckprompt.Command` installs available `show` and `list` operations beneath the owned `promptkit` namespace. | Assemble the requirements operation from its own capability. |
| Invocation infrastructure | Typed selectors, configuration selection, input checks, shared state, diagnostics, and buffered report delivery already exist. | Apply those paths to the new operation. |
| Presentation | Named prompt/profile reports support text and YAML; catalogs use YAML only. | Define a requirements report with the native evidence and discovery context identities. |

The [deferred-work record](deferred.md#promptkit-requirement-inspection) records
this capability's prior deferral. This roadmap takes it up for planning;
the command remains unimplemented. Existing configuration, catalog, and named
definition operations are not prerequisites for enabling requirements inspection.

## Target ownership and package boundaries

| Owner | Responsibility |
| --- | --- |
| PromptKit | Prompt/profile/version selection semantics, context interpretation, discovery, classifications, completeness, structured issues, disclosure rules, and native errors. |
| `integrations/ckprompt` | The optional callback, request adaptation, command declaration, engine adapter, requirements report, and integration-specific outcome coordination. |
| `integrations/ckconfig` | Existing configuration selection and reusable configuration adaptation paths consumed by ckprompt. |
| CommandKit core | Captured declarations, bindings, parsing, installation, dispatch, help, diagnostics, and outcomes. |
| Consuming application | Engine acquisition, application selectors and checks, runtime state, custom providers, and any application-owned effects. |

Keep the dependency direction `ckprompt → ckconfig → core`, with ckprompt also
using core and PromptKit directly. This feature belongs in ckprompt; it does not
require PromptKit types in core, a reverse ckconfig dependency, or a new module.
Use the existing public facade and internal backend boundary.

## Target operator surface

Selected operation:

```sh
app promptkit requirements show PROMPT_ID
app promptkit requirements show briefing --version 2 --profile editorial --var audience=internal --var language=en
app promptkit requirements show briefing --session-id session-42 --var note= --format yaml
```

The `requirements` resource namespace follows the resource-first pattern of
`config show` and gives future requirements operations a location without
selecting them for this delivery.

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 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.

### 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

Return the native input and variable inventories, including optional and
conditional entries. Carry selected identities, metadata presence,
classifications, completeness, explanations, and structured issues into the
report. Preserve the returned inventories and issues without introducing a
second analyzer, filtering out partial evidence, or interpreting explanation
strings as machine-readable rules.

`Complete` describes discovery coverage. It does not mean that dependencies are
supplied, artifacts are valid, templates will render, or execution is ready.
A complete inspection can contain an unsupplied required variable. An incomplete
inspection can still provide a useful inventory. The command's documentation
should explain this distinction and link to the adopted PromptKit contract.

For a successfully acquired and delivered inspection, return success (status
`0`), including when `Complete` is false or structured issues are present.
Discovery issues are report data; they do not independently become fatal
CommandKit diagnostics. Existing acquisition diagnostics and diagnostic delivery
rules still apply.

Apply the established outcomes to actual failures:

- CLI syntax, operand, format, and variable-assignment parsing failures are usage
  failures (status `2`).
- Engine acquisition, native selection or inspection, cancellation, and report
  delivery failures use the existing operational paths (status `1`), preserving
  supported public error identity. Input checks and application-supplied
  classifications retain their existing handling.
- A provider that returns no inspection and no error is a provider failure,
  consistent with existing named inspection handling.

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 selected standard
operation, not new restrictions on application loaders or custom callbacks.

PromptKit does not return supplied variable values as a separate inventory of
values. A resolved input identifier can nevertheless equal a supplied value and
is intentionally included. Preserve the adopted disclosure contract; do not
invent blanket masking or a guarantee that application content can never appear
in output.

## Target public integration and lifecycle

Add this request type in ckprompt:

```go
type RequirementsRequest struct {
    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
`Engine.InspectRequirements`. Applications can clear, wrap, or replace it using
ordinary suite composition. No additional registration mechanism is needed.

When only this callback is present, `ckprompt.Command` installs a usable
`promptkit requirements show` command without empty catalog or named-definition
groups. A nil requirements callback omits its operation without disabling the
others. When every callback is absent, retain the existing absent-family
behavior and attached wiring errors. Namespace ownership continues to follow
actual installation.

Apply captured selector metadata and the existing preparation lifecycle: prepare
one application input, apply applicable selectors, finish preflight and input
checks, then initialize shared state and invoke the selected provider. Omitted
factories retain zero-value behavior. Construction, installation, help, and
version leave factories and acquisition callbacks uninvoked, as required by the
existing contracts.

Keep parsed variable storage local to the invocation. Do not introduce arbitrary
deep-copy promises for caller input/state or inspection results. Reuse existing
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.

## Initial report

Use YAML only initially, defaulting to YAML and accepting `--format yaml`
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 |
| --- | --- |
| Selected context and coverage | `prompt_id`, `prompt_version`, `profile_id`, `complete` |
| `inputs` entries | `name`, `kind`, `declared`, `content_type`, `description`, `explanation` |
| `variables` entries | `name`, `kind`, `supplied`, `explanation` |
| `issues` entries | `code`, `input_name`, `variable_name`, `description` |

Include false boolean values and represent empty inventories as sequences
(`[]`). For nullable input metadata, preserve the distinction available from
PromptKit: nil becomes YAML null, while an explicitly empty string remains
`""`. Do not attempt to distinguish absent metadata from an explicit upstream
null when the native API does not distinguish them. Preserve native kind and
issue-code values rather than rejecting future values solely because they are
not in today's set.

Illustrative shape, showing that complete discovery can still identify an
unsupplied variable:

```yaml
prompt_id: briefing
prompt_version: "2"
profile_id: editorial
complete: true
inputs: []
variables:
  - name: audience
    kind: required
    supplied: false
    explanation: ""
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; these examples do not define PromptKit discovery behavior.

## Delivery and documentation targets

The [implementation plan](implementation.md) defines adaptation, command
assembly, presentation, validation, and documentation work from the baseline.
The maintained composed consumer should demonstrate a partial inventory and how
supplying discovery context changes it, with both delivered reports returning
status `0`. Focused native and boundary coverage should substantiate the selected
contracts without duplicating upstream's full analysis suite or adding new
validation infrastructure, performance guarantees, or release gates.

At delivery, ckprompt GoDoc, the CLI reference, consumer guidance, and relevant
internal summaries describe the implemented capability under their existing
ownership rules. The deferred-work record reflects its actual status. The new
operation fits the existing ownership and registration boundaries and requires
no new ADR; ADR 0004 remains unchanged. Command spelling and report/API details
belong with their canonical owners when implemented.

Release documentation and module version selection follow the existing release
procedure when a release is prepared. No upstream release, dependency bump,
publication, or consumer migration is required by this roadmap.

## Completion boundary

The target is reached when an application can independently enable the new
operation, select native discovery context, and receive the requirements report
with the established lifecycle, diagnostic, error, and delivery handling. The
maintained example and canonical documentation should demonstrate its purpose
and explain completeness accurately.

Initial delivery does not include a requirements assertion mode, execution
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.

The decisions needed for an implementation plan are settled.