Document prompt requirement inspection

docs/consumers/pkg-promptkit.md

@@ -154,6 +154,50 @@ rendered messages, and use prepared execution when that work must remain tied
 to later execution. The method's [GoDoc](../../engine.go) owns exact fields,
 hash, ownership, and error semantics.
 
+## Inspect Requirements Before Preparation
+
+Use [`Engine.InspectRequirements`](../../requirements.go) when the application
+needs the prompt's recognizable input and caller-variable dependencies for a
+particular context before it has input artifacts. Unlike `InspectPrompt`, it
+also walks captured template syntax and selects a profile identity; unlike
+`Prepare`, it does not load artifacts or render messages.
+
+```go
+requirements, err := engine.InspectRequirements(ctx, promptkit.RequirementInspectionRequest{
+	PromptID: "meeting.summary",
+	Vars:     map[string]string{"audience": "project leads"},
+})
+if err != nil {
+	return err
+}
+
+for _, input := range requirements.Inputs {
+	if input.Kind == promptkit.RequirementRequired {
+		// Plan to bind this input before preparation.
+	}
+	if input.Kind == promptkit.RequirementOptional && input.Explanation != "" {
+		// A recognizable reference may occur only on a known skipped path.
+	}
+}
+for _, variable := range requirements.Variables {
+	if variable.Kind == promptkit.RequirementRequired && !variable.Supplied {
+		// The key is required even though this inspection did not receive it.
+	}
+}
+if !requirements.Complete {
+	// Preserve the partial inventory and account for its discovery issues.
+}
+```
+
+Optional entries can include recognizable inputs and variables found only in
+inactive branches. A missing required variable is reported separately from
+discovery completeness: missing a value used only for direct text substitution
+does not by itself make the inventory incomplete. Conversely, an unresolved
+dependency-bearing branch can make discovery incomplete while retaining known
+conditional entries. Do not treat an empty partial inventory as proof that no
+input bindings are needed. See the method's [GoDoc](../../requirements.go) for
+the exact classifications, supported syntax, ownership, and error contract.
+
 ## Prepare Without Model Execution
 
 [`Engine.Prepare`](../../engine.go) resolves the selected prompt and profile,

docs/formats.md

@@ -124,6 +124,12 @@ Optional `session_id` uses the same template variables and input helper. Its
 rendered value is trimmed, omitted if empty, and limited to 256 Unicode code
 points. A nonblank direct request session ID bypasses the template.
 
+`InspectRequirements` can enumerate recognizable dependencies from captured
+templates before artifact content is available. Its conservative syntax
+coverage does not change template validity or rendering; see the [consumer
+guide](consumers/pkg-promptkit.md#inspect-requirements-before-preparation) and
+the method's [GoDoc](../requirements.go) for that inspection boundary.
+
 ### Cache Control
 
 Optional `cache_control` has required `type: ephemeral` and optional `ttl`,

docs/roadmap/implementation.md

@@ -416,6 +416,13 @@ suite solely for this unit; commit.
 
 ## Stage 7 — Document And Verify The Assembled Feature
 
+**Status: Complete (2026-10-08).** GoDoc, consumer guidance, framework-format
+cross-references, and the maintained preparation example now describe the
+implemented discovery boundary. Final offline verification passed:
+`go test -race -vet=off -mod=readonly -count=1 ./...`,
+`go vet -mod=readonly ./...`, and `python3 scripts/check-examples.py`, with
+`GOTOOLCHAIN=local GOWORK=off GOPROXY=off GONOPROXY=none GOSUMDB=off`.
+
 **Outcome:** Implemented semantics and analysis limits are documented in their
 canonical owners, with final verification ready for user review.
 

docs/roadmap/inspection.md

@@ -1,8 +1,10 @@
 # Effective Prompt Requirement Inspection
 
-Status: Implementation planned; the feature is not implemented. The
-[implementation plan](implementation.md) owns the ordered implementation steps.
-This document owns the purpose, scope, and target end state.
+Status: Implemented (2026-10-08). The
+[implementation plan](implementation.md) records the completed work units and
+final verification. Current public API details live in GoDoc; the consumer
+guide, format reference, and internal documents link to those canonical
+contracts.
 
 ## Purpose
 
@@ -16,7 +18,7 @@ The originating request is [Scriptorium's feature request](scriptorium-feature-r
 Promptkit supplies application-neutral inspection; consumers own presentation,
 binding checks, and their own workflows.
 
-## Current Baseline
+## Original Review Baseline
 
 At review baseline `b595dca`:
 
@@ -183,28 +185,19 @@ metadata. A directly resolved input identifier may equal a supplied variable
 value; reporting that binding name is necessary, without echoing its originating
 expression or variable map.
 
-## Work Needed From The Baseline
+## Implemented Outcome
 
-Add request/result values and the engine method through the root facade.
-Keep selection coordination internal and place syntax discovery with the
-existing prompt-template component. Reuse captured templates and selection
-helpers rather than creating another preparation path.
+The root API selects a captured prompt and profile identity, then returns
+caller-owned input and variable inventories with conservative classifications
+and structured discovery limitations. The internal prompt walker uses captured
+template syntax and effective metadata; inspection does not enter artifact,
+schema, credential, rendering, provider, or execution preparation.
 
-Capture required metadata presence at the final ConfigKit handoff and retain it
-alongside inspection snapshots. Apply [ADR 0001](../adr/0001-configuration-boundary.md):
-interpret final effective definitions, not raw/intermediate configuration or
-history. Operator provenance remains a separate explicit API.
-
-Implement a small syntax walker, simple context tests, classification
-aggregation, and safe limitation reporting. Keep request-specific state separate
-from captured definitions. Focus tests on representative enumeration,
-classifications, scope mistakes, selection, capture/ownership, and absence of
-execution effects, under the [testing policy](../policy/testing.md). Do not test
-a general interpreter or repeat ConfigKit's source-loading matrix.
-
-When implementation lands, update GoDoc, the consumer guide, relevant format
-cross-references, internal documents, and a maintained example. Canonical owners
-document the implemented boundary; release notes summarize rather than own it.
+The final verification and the commit sequence are recorded in the
+[implementation plan](implementation.md). The exact public contract is owned by
+[GoDoc](../../requirements.go); consumer usage, framework-format cross-reference,
+and internal selection/source descriptions are maintained in their respective
+documents.
 
 ## Acceptance Outcomes