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

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