Settle requirement inspection scope

docs/roadmap/inspection.md

@@ -2,9 +2,8 @@
 
 Status: Implementation planned; the feature is not implemented. The
 [implementation plan](implementation.md) owns the ordered migration steps and
-uses the recommended scope below. Open Decisions still records the alternative
-scope choices for confirmation. This document owns the target end state and
-migration scope.
+implements the agreed analysis scope and inventory below. This document owns
+the target end state and migration scope.
 
 ## Purpose
 
@@ -80,6 +79,10 @@ The result contains:
   available. A template-discovered undeclared input must not look like a
   declared input with known metadata. Report existing media-type metadata,
   not an invented input schema or inferred format constraint.
+- An inactive-use explanation for statically identifiable undeclared inputs
+  referenced only on known inactive paths. These are optional inventory entries,
+  not bindings the current context needs. Keep this explanation separate from
+  declared descriptions.
 - Variable requirements separately from artifact inputs, with requirement
   classification and whether supplied values satisfy the known requirement.
   Report presence and actual supported semantics, not the supplied values.
@@ -94,9 +97,15 @@ means its requirement depends on unresolved context. Do not use optional to
 hide uncertainty. Known required declarations retain that classification even
 when other requirements are conditional or undiscoverable.
 
-An unresolved dynamic name can refer to a declared optional input. Its absence
-from recognized active uses alone does not establish that it is definitely
-optional; classification and uncertainty must account for that possibility.
+Include statically identifiable undeclared references on known inactive paths
+as optional entries with an inactive-use explanation. A required or conditional
+use elsewhere takes precedence over that inactive-only classification and
+explanation. Inactivity itself is not discovery uncertainty.
+
+An unresolved dynamic name can refer to an otherwise optional input entry. Its
+absence from recognized active uses alone does not establish that it is
+definitely optional; classification and uncertainty must account for that
+possibility.
 
 Known input names should be deduplicated across declarations, messages, and
 session templates. Aggregate uses without discarding an established required
@@ -108,7 +117,10 @@ a missing variable used only to insert text can be a known unsatisfied
 requirement while the complete input set is still discoverable. If that
 variable selects an input name or branch, its absence can also make discovery
 incomplete. An empty complete input set means no artifact bindings are needed;
-an empty incomplete set does not establish that fact.
+a complete inventory containing only optional entries also needs no artifact
+bindings. An empty incomplete set does not establish that fact. Consumers must
+distinguish the inventory from applicable requirements, rather than treating
+every reported name as a needed binding.
 
 ## Context-Sensitive Discovery Boundary
 
@@ -121,6 +133,7 @@ nonempty string must not be reinterpreted as a Boolean merely from its spelling.
 Include dependencies from messages and the applicable session-ID template.
 A direct nonblank session ID bypasses that template, removing only requirements
 introduced solely by it; declarations and message uses remain relevant.
+The bypassed session template is also excluded from the inactive inventory.
 
 Literal `input` references are discoverable without reading bodies, including
 undeclared references. Artifact content being unavailable does not by itself
@@ -136,8 +149,8 @@ analysis is not a new prompt-validity rule. Completeness is asserted only when
 the supported analysis establishes the requirement set; it does not promise
 universal analysis of every valid Go template.
 
-The initial analysis coverage and inactive-reference inventory are the Open
-Decisions below. They do not change execution or expand the template language.
+The selected practical analysis core and inactive inventory are described below.
+They do not change execution or expand the template language.
 
 ## Effects, Errors, And Disclosure
 
@@ -209,24 +222,29 @@ not own its contract. The implementation plan owns implementation sequencing.
   absence from declarations a new definition error.
 - Declared required inputs remain required in inactive branches; optional
   declarations remain optional where no applicable use makes them required.
+- Statically identifiable inactive undeclared references are optional entries
+  with an inactive-use explanation; active and unresolved uses of the same name
+  take precedence. These entries do not introduce variable requirements or
+  incompleteness solely from skipped expressions.
 - Supported variable-dependent branches and names agree with execution;
   unresolved content/name/analysis cases retain known entries and uncertainty.
 - Version/profile/default selection and session-template bypass agree with
   execution without credential or generation-readiness checks.
 - Variables are reported separately, with absent and empty supplied values
   interpreted according to the existing template semantics.
-- No-input completeness is distinguishable from empty partial discovery.
+- Artifact-free complete results, including all-optional inventories, are
+  distinguishable from empty partial discovery.
 - Errors remain publicly classifiable; results and safe diagnostics disclose
   identifiers and declared metadata without unrelated content or secret values.
 - Existing inspection and execution APIs retain their contracts. Pipeline
   planning, binding validation, CLI/HTTP exposure, presentation, JSON schemas,
   graph rendering, batch interfaces, and provider preflight remain downstream.
 
-## Open Decisions
+## Selected Analysis Scope And Inventory
 
 ### Initial Template Analysis Coverage
 
-**Recommendation:** Implement a documented practical core: literal input calls,
+Implement a documented practical core: literal input calls,
 direct caller-variable access, ordinary `if`/`with` control flow, and simple
 variable-derived names and comparisons where their values are determinable.
 Account for template variable scope and short-circuit behavior for supported
@@ -236,24 +254,20 @@ implementation plan specifies the exact expression families for this baseline.
 This covers the representative consumer needs while keeping completeness
 honest and avoiding a second general-purpose interpreter.
 
-**Alternative:** Support substantially broader Go-template evaluation now,
-including loops, named templates, and more built-in pipelines. It would produce
-complete results for more existing prompts, but increases semantic machinery,
-maintenance, and parity-testing costs. It still cannot determine decisions based
-on unavailable artifact contents. Prefer it if concrete consumer examples show
-that the practical core would frequently return unhelpful partial results.
-
 ### Inactive Undeclared Reference Inventory
 
-**Recommendation:** Always include declarations, plus template-discovered names
-needed on active or unresolved paths. Omit undeclared names used solely in a
-branch known to be inactive. Conditional names on unresolved paths remain
-explicitly conditional. This keeps the result focused on the effective caller
-requirements and avoids presenting irrelevant bindings as work to prepare.
+Always include declarations and discovered active or unresolved dependencies.
+Also include statically identifiable undeclared references on known inactive
+paths as optional entries with an inactive-use explanation. This broader
+inventory helps operators explore prompt behavior while preserving the
+distinction between inventory and applicable dependencies.
 
-**Alternative:** Also list statically identifiable undeclared references on
-known inactive paths, marking them optional with an inactive-use explanation.
-This gives operators a broader inventory for exploring prompt behavior, but
-adds irrelevant names and requires consumers to distinguish that inventory
-from applicable dependencies. Either choice must preserve declared optional
-metadata and must not classify a known inactive use as required.
+Collect inactive names from syntax without evaluating skipped expressions.
+The initial scope covers literal helper names and equivalent parenthesized or
+piped literal forms. Skipped dynamic names need not be resolved, and skipped
+variable accesses do not become caller requirements or uncertainty reasons.
+Include known skipped branches and short-circuit operands, without expanding
+analysis to never-invoked template definitions or a bypassed session template.
+Preserve declared optional metadata and required declarations; when another
+use makes a name required or conditional, its inactive occurrence does not
+override that classification or imply that the name is inactive-only.