diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a6eedf482..fb4eaa4c7 100644 --- a/docs/AGENTS.md +++ b/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. --- diff --git a/docs/explanation/security-model.md b/docs/explanation/security-model.md index ab5523b74..e4073a874 100644 --- a/docs/explanation/security-model.md +++ b/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 `` +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 diff --git a/docs/how-to/design-a-ui-phase.md b/docs/how-to/design-a-ui-phase.md index d4527c5b5..2ae9a4ac3 100644 --- a/docs/how-to/design-a-ui-phase.md +++ b/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 + `@` 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