Store one prompt definition per ID

docs/formats.md

@@ -12,10 +12,10 @@ This reference describes what Promptkit does with the final effective values.
 
 A configuration document has keyed top-level `backends`, `profiles`, and
 `prompts` mappings. Their keys are literal IDs, not filename-derived identities.
-Prompt versions are a second keyed mapping. Keys and references must be
-nonblank and remain exact: Promptkit does not trim or re-key them. Old embedded
-`id`, `version`, and `base_profile` fields are invalid. Unknown fields are
-errors.
+Each prompt ID maps directly to one definition; an optional `version` string is
+descriptive metadata, not a selection key. Keys and references must be nonblank
+and remain exact: Promptkit does not trim or re-key them. Old embedded `id` and
+`base_profile` fields are invalid. Unknown fields are errors.
 
 ```yaml
 backends:
@@ -28,14 +28,14 @@ profiles:
     model: example-model
 prompts:
   meeting.summary:
-    "1.0.0":
-      default_profile: local-summary
-      messages:
-        - role: user
-          content: Summarize this note.
-      output:
-        format: text
-        validation_mode: none
+    version: "1.0.0"
+    default_profile: local-summary
+    messages:
+      - role: user
+        content: Summarize this note.
+    output:
+      format: text
+      validation_mode: none
 ```
 
 Every effective backend, profile, and prompt definition is validated when
@@ -56,32 +56,32 @@ see the consumer guide's [profile and prompt listing](consumers/pkg-promptkit.md
 
 ## Prompt Definitions
 
-The `prompts` mapping selects a literal prompt ID, then a string version key:
+The `prompts` mapping selects a literal prompt ID whose value is the definition:
 
 ```yaml
 prompts:
   meeting.summary:
-    "1.0.0":
-      default_profile: local-summary
-      description: Summarize a synthetic meeting note.
-      session_id: '{{.session}}'
-      inputs:
-        - name: note
-          required: true
-          content_type: text/plain
-          description: Meeting note to summarize.
-      messages:
-        - role: system
-          content: Return a concise summary.
-          cache_control:
-            type: ephemeral
-            ttl: 1h
-        - role: user
-          content_file: ./summary.user.md
-      output:
-        format: markdown
-        validation_mode: basic
-        repair_attempts: 0
+    version: "1.0.0"
+    default_profile: local-summary
+    description: Summarize a synthetic meeting note.
+    session_id: '{{.session}}'
+    inputs:
+      - name: note
+        required: true
+        content_type: text/plain
+        description: Meeting note to summarize.
+    messages:
+      - role: system
+        content: Return a concise summary.
+        cache_control:
+          type: ephemeral
+          ttl: 1h
+      - role: user
+        content_file: ./summary.user.md
+    output:
+      format: markdown
+      validation_mode: basic
+      repair_attempts: 0
 ```
 
 `messages` must be nonempty and `output` must be a valid mapping. Optional
@@ -89,9 +89,8 @@ prompts:
 fields may be absent or cleared with null where appropriate. A null whole
 definition, required role, output format, or validation mode is invalid.
 `required` and `repair_attempts` default to false and zero, respectively, and
-are not nullable. A request that omits a prompt version succeeds only if that
-prompt ID has exactly one effective version. `InspectPrompt` selects from the
-same captured definitions without rendering or resolving a profile.
+are not nullable. `InspectPrompt` selects the same captured definition without
+rendering or resolving a profile.
 
 ### Inputs
 

docs/roadmap/implementation.md

@@ -390,6 +390,13 @@ Validation: `GOWORK=off go test ./...`, including consumers of migrated fixtures
 Test ID-only selection, source-relative content, and inherited/overlaid prompt
 settings. Do not add tests preserving temporary obsolete selector parameters.
 
+Completion: prompts now map directly from each ID to one definition, with an
+optional descriptive version label. Configuration lookup and message/input
+metadata paths are ID-only; ambiguity handling and version-keyed indexes are
+removed. Fixtures, examples, and the canonical format reference use the direct
+shape, including layered overlays. Validation passed: `GOWORK=off go test ./...`,
+`GOWORK=off python3 scripts/check-examples.py`, and `git diff --check`.
+
 ## Stage 5: Remove Request-Side Version Selection
 
 Scope: compile-directed removal of obsolete selector plumbing; no new lookup rules.