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>
This commit is contained in:
Tom Boucher
2026-08-21 13:22:50 -04:00
committed by GitHub
parent 4918c62d76
commit dacae92730
3 changed files with 42 additions and 1 deletions

View File

@@ -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