docs(#2845): record the inventory-provenance limits where readers meet them (#3746)

The limits shipped with #2845 were disclosed only in the PR body, which is
read once at merge and then buried. They are properties of what the feature
does, so they belong in the documentation.

Three surfaces, each at the point a reader forms an expectation:
docs/how-to/design-a-ui-phase.md gains a 'What this check is and is not'
subsection under the provenance how-to; docs/explanation/security-model.md
gains a residual-risk pair matching the section's existing shape; and
docs/AGENTS.md notes them where gsd-ui-checker's behavior is described.

The substance: a provenance line makes an inventory's origin falsifiable
rather than verified, since nothing re-runs the command or compares the
count; the rule is agent-applied like the other six dimensions, not a schema
check; and 'the checker never runs the recorded command' is an instruction
rather than a capability boundary, because the checker holds a Bash grant it
genuinely needs for the agent-skills bootstrap and tool grants here are not
command-scoped.

Co-authored-by: sim <sim@local>

docs/AGENTS.md

@@ -309,7 +309,7 @@ Two further dimensions carry no number: **Verify Command Format Sanity** and
 | 7 | Inventory Provenance |
 
 **Key behaviors:**
-- **Inventory provenance (#2845):** a UI-SPEC whose component inventory carries no provenance line is reported as a defect, and the inventory is downgraded from a closed allowlist to a **non-exhaustive list of known-good components** — so an executor is never blocked from something the spec merely failed to mention. A spec with no inventory at all PASSes, which is what keeps every UI-SPEC written before the dimension existed validating unchanged. The checker never executes the recorded command; it reads the spec as a document.
+- **Inventory provenance (#2845):** a UI-SPEC whose component inventory carries no provenance line is reported as a defect, and the inventory is downgraded from a closed allowlist to a **non-exhaustive list of known-good components** — so an executor is never blocked from something the spec merely failed to mention. A spec with no inventory at all PASSes, which is what keeps every UI-SPEC written before the dimension existed validating unchanged. The checker never executes the recorded command; it reads the spec as a document. **Limits, because the dimension is narrower than it reads:** the line makes an inventory's origin falsifiable, not verified — nothing re-runs the command or compares the count, so a fabricated line passes; the rule is agent-applied like the other six, not a schema check; and "never executes the recorded command" is an instruction rather than a capability boundary, since the checker holds a `Bash` grant it needs for the agent-skills bootstrap. See [Security model → Trade-offs and limits](explanation/security-model.md#trade-offs-and-limits) and [How to design a UI phase](how-to/design-a-ui-phase.md#what-this-check-is-and-is-not).
 - **Adversarial stance / "The Auditor" (#1578):** applies explicit BLOCK/FLAG/PASS tiers and an anti-capitulation rule that resists author-framing pressure while still allowing self-correction when the prior dimension application was mistaken. Persona effects are strongest on Sonnet-class reasoning and unvalidated on budget/Haiku-class routing; the criteria and evidence remain authoritative.
 
 ---

docs/explanation/security-model.md

@@ -337,6 +337,26 @@ research agents — but novel jailbreaks and low-signal injections may still pas
 undetected. Defence in depth means each layer makes the attack harder, not that
 any single layer makes it impossible.
 
+**What the UI-SPEC provenance rule does not eliminate:** `gsd-ui-checker`
+Dimension 7 requires a component inventory to record the command that
+enumerated it, and instructs the checker never to run that command — it is
+text from a document, not an instruction to the agent. **That barrier is
+prompt-level only.** The checker holds a `Bash` grant it genuinely needs (the
+agent-skills bootstrap shells out through `gsd_run`), and tool grants here are
+not command-scoped, so nothing structurally prevents execution of a command
+string lifted out of a UI-SPEC. No shipped instruction does so, and the spec is
+written by `gsd-ui-researcher`, which carries the `<security_context>`
+untrusted-input boundary for its web and MCP ingress — but this is defense by
+instruction, not by capability. The same shape is older and wider in Dimension 6,
+where the *researcher* is told to run `npx shadcn view {block} --registry {url}`
+with a registry URL taken from the spec; there the execution is the vetting
+gate's purpose rather than something to suppress.
+
+Note also what a provenance line is worth: it makes an inventory's origin
+**falsifiable, not verified**. A fabricated line passes the dimension. Its value
+is that the recorded command can be re-run by a reader, which was not possible
+before the field existed.
+
 **What subprocess execution does not eliminate:** `cmd.exe` expands `%VAR%`
 inside a `/c` string, and there is no escape for `%` outside a batch file. An
 argument containing `%FOO%` is therefore substituted with the environment

docs/how-to/design-a-ui-phase.md

@@ -144,6 +144,27 @@ expected path, not an exception.
 The checker never runs the recorded command. It reads the spec as a document; executing a command
 string lifted out of one would be a code-execution path through untrusted text.
 
+### What this check is and is not
+
+Worth knowing before you rely on it, because the check is narrower than it looks:
+
+- **It makes the inventory's origin falsifiable, not verified.** Nothing re-runs the command or
+  compares the count against the installed package. A line that was simply made up passes. What
+  you gain is that a reader — or you, six months later — can re-run the recorded command and see
+  for yourself; before the field existed there was nothing to re-run.
+- **It cannot tell a stale inventory from a current one.** That is what the recorded
+  `<package>@<version>` is for: compare it against what is installed now. A spec reused after an
+  upgrade looks exactly like a fresh one apart from that string.
+- **Enforcement is applied by an agent, not by a parser.** Dimension 7 is a rule `gsd-ui-checker`
+  follows, the same as the other six dimensions. It is not a schema check that runs over your
+  spec, so treat a PASS as "the reviewer found a provenance line", not as a machine guarantee.
+- **"The checker never runs the recorded command" is an instruction, not a sandbox.** See
+  [Security model → Trade-offs and limits](../explanation/security-model.md#trade-offs-and-limits)
+  for why that distinction matters and what does back it up.
+
+None of this makes the field pointless — an unsourced inventory used to be indistinguishable from
+a sourced one, and now it is not. But it is a record you can audit, not a proof.
+
 ---
 
 ## Use sketch findings as a head start