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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user