Define profile and prompt listing

docs/roadmap/listing.md

@@ -0,0 +1,118 @@
+# Profile And Prompt Listing
+
+Status: Accepted; implementation pending.
+
+## Purpose
+
+Let consumers discover the profiles and prompt versions available in an engine
+without knowing their identifiers in advance or interpreting configuration
+history. This supports application selectors, CLI discovery, and configuration
+editors while keeping PromptKit's public API small.
+
+Listing supplies identities; the existing inspection methods supply details.
+A separate implementation plan will define staged work. This roadmap describes
+the intended feature, not currently available methods.
+
+## Current Baseline
+
+Review baseline: `03c44923c8a14565dca30f65d93bde79e0962ea2`.
+
+- `Engine.InspectProfile` and `Engine.InspectPrompt` inspect a known identity.
+  Neither enumerates available entries.
+- `Engine.InspectConfiguration` exposes ConfigKit's captured inspection view.
+  Consumers can enumerate historical paths and filter for surviving effective
+  entries, but that is an indirect configuration-inspection workflow.
+- The configuration adapter already captures profiles by literal ID and prompts
+  by literal ID/version pair. Those execution-facing indexes are sufficient
+  for listing; no new configuration loading or registry is needed.
+
+The [consumer guide](../consumers/pkg-promptkit.md) describes existing inspection
+workflows. The [format reference](../formats.md) owns keyed definitions and
+literal identifier semantics. Preserve the final-configuration boundary in
+[ADR 0001](../adr/0001-configuration-boundary.md) and the facade ownership in
+the [architecture policy](../policy/architecture.md).
+
+## Target End State
+
+### Small Public Listing API
+
+Add two engine methods, following the context and error conventions of the
+existing prompt/profile inspection methods:
+
+- `ListProfiles(ctx)` returns profile IDs.
+- `ListPrompts(ctx)` returns small identity values containing `ID` and `Version`.
+
+Expose only the identity value needed for prompt listing. GoDoc will own the
+exact signatures and behavior when implemented. Callers can pass the returned
+identities to `InspectProfile`, `InspectPrompt`, or their execution requests.
+Bulk inspection results, prompt text, execution targets, source provenance,
+and credential information do not belong in these results.
+
+### Effective Captured Inventory
+
+List the identities present in the engine's final captured configuration,
+including maintained catalog profiles and consumer-defined profiles and
+prompts after ConfigKit layering and inheritance. A profile's configured alias
+or inherited identity remains its own list entry, not its base profile's name.
+Historical or superseded contributions do not create additional entries.
+
+Each effective profile ID appears once. Each effective prompt ID/version pair
+appears once, including every configured version of a multi-version prompt.
+Listing does not choose a default or latest version; the existing omitted-version
+selection behavior remains unchanged.
+
+Preserve exact identifier spelling. Return profiles in ascending lexical ID
+order and prompts in ascending lexical ID order, then lexical version order.
+Version ordering is for deterministic presentation, not semantic-version
+comparison or a recommendation about which version to execute.
+
+### Lightweight Snapshot Read
+
+Listing reads the engine's captured identity indexes. It does not reload sources
+or files, analyze configuration provenance, resolve credentials, read artifacts
+or schemas, render, acquire backend capacity, or contact providers.
+
+A profile need not be execution-ready to be listed. Presence in the inventory
+does not promise valid credentials, provider availability, or successful
+execution. Catalog entries remain subject to the existing
+[catalog compatibility policy](../policy/release.md#catalog-profile-compatibility).
+
+Returned slices are caller-owned; modifying one result cannot change the
+engine or later results. Listing supports concurrent engine use without adding
+mutable registry state. An empty inventory is a successful result. A nil engine
+uses `ErrInvalidConfig`, and cancellation preserves the context error under the
+existing inspection conventions.
+
+## Work Needed From The Baseline
+
+- Add identity-only enumeration to the captured configuration adapter and route
+  it through the internal engine to the public facade. Keep internal
+  representations behind the existing package boundary.
+- Add the two public methods and the small prompt identity value, with GoDoc.
+  Avoid obtaining each item's full inspection or copying profile parameters
+  and prompt content merely to list its identity.
+- Keep traversal and allocation proportional to the inventory returned.
+  Prefer straightforward reuse of captured indexes; ordering can be prepared
+  during construction rather than repeatedly sorting unchanged identities.
+  Exact storage layouts and allocation counts are implementation choices.
+- Add focused tests for effective inventory membership, multiple prompt
+  versions, literal identities and ordering, caller ownership, empty results,
+  and the selected error/cancellation behavior. Include a representative public
+  workflow that lists entries and inspects a returned identity. Reuse existing
+  construction coverage rather than retesting ConfigKit's resolution machinery.
+- Add concise listing guidance to the consumer guide and update the relevant
+  internal documentation when implemented. Preserve existing inspection and
+  execution contracts.
+
+Backend enumeration, filtering, pagination, runtime registration, and live
+catalog/provider discovery are outside this feature's scope. No new caller
+limits, readiness checks, release gates, or performance guarantees are needed.
+
+## Completion
+
+Consumers can enumerate effective profiles and exact prompt versions through
+the public facade, obtain independent deterministic results, and use those
+identities with existing operations. Verification follows the
+[testing policy](../policy/testing.md), including focused ownership and
+concurrent-use checks proportionate to the implementation. Current documentation
+describes the implemented API without duplicating ConfigKit history semantics.