From e5faa1855d0caef1b0e60c4bca37126c8f7be1b1 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Mon, 12 Oct 2026 17:43:54 +0000
Subject: [PATCH] Document requirements variable report fields

---
 docs/cli.md                 | 16 +++++++++++++---
 docs/roadmap/remediation.md | 11 +++++++++--
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index 84e9d3b..c56f5ed 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -428,7 +428,13 @@ occurrence is a usage error even if a later assignment is valid.
 The successful report is YAML with selected identities, native completeness,
 and the input, variable, and issue inventories. False values and empty
 inventories are retained. Input metadata preserves null versus an empty string.
-The shape is:
+Variable entries contain `name`, `kind`, `supplied`, and `explanation`.
+`supplied` reports native exact-key presence, including an explicitly empty
+value, independently of `kind` and `complete`. Explanations and issue descriptions
+are upstream-owned human-readable summaries, not machine-readable details.
+
+For a prompt with the template `{{if .mode}}{{input "notes"}}{{end}}` and no
+input declarations, omitting `mode` can produce this partial report:
 
 ```yaml
 prompt_id: briefing
@@ -441,13 +447,17 @@ inputs:
     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: ""
-variables: []
 issues:
   - code: missing_variable
     input_name: ""
     variable_name: mode
-    description: ""
+    description: A missing variable prevents selecting a dependency-bearing branch.
 ```
 
 PromptKit owns the inventory, classifications, explanations, completeness,
diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md
index 0b08dbe..63ff552 100644
--- a/docs/roadmap/remediation.md
+++ b/docs/roadmap/remediation.md
@@ -1,6 +1,6 @@
 # PromptKit requirements inspection review
 
-Status: R-1 completed; R-2 and R-3 open. This document records follow-up work;
+Status: R-1 and R-2 completed; R-3 open. This document records follow-up work;
 the review does not change implementation or current contracts.
 
 ## Review scope and authority
@@ -57,7 +57,7 @@ or test changes were needed.
 
 ## R-2: Complete the canonical requirements YAML schema
 
-Status: open. Priority: normal. Category: incomplete documentation delivery.
+Status: completed. Priority: normal. Category: incomplete documentation delivery.
 
 **Evidence:** [CLI reference](../cli.md), lines 428–451, describes the report
 shape but illustrates `variables: []` without defining variable-entry fields
@@ -90,6 +90,13 @@ owner, and the example matches the existing native/consumer evidence. Review
 local links and document whitespace. Production serialization and test fixtures
 need no changes to repair this omission.
 
+**Completed:** Documented all four variable-entry fields and native exact-key
+presence independently of classification/completeness. The partial-report example
+now includes the unsupplied `mode` entry and upstream human-readable summaries.
+Reviewed all example fields against the private report types and existing native
+and report coverage; a field-inventory check, local links/fragments, and
+`git diff --check` passed. Production serialization and fixtures are unchanged.
+
 ## R-3: Remove an incidental YAML key-order requirement from a test
 
 Status: open. Priority: low. Category: inadvertently strengthened test contract.