One-line install prompt + guide fixes from two more field tests#46
Merged
Conversation
A real-world refusal (WebContainer/Bolt-style agent) exposed a fourth refusal mode: unbounded "finish what it prints" delegation and a bare claim URL that reads as machine authorization. The new one-line README prompt bounds the delegation by naming the checklist's steps (build hooks + widget snippet), states the claim URL's purpose (user opens it in a browser to view reports), and links npmjs.com for verification. A simulated agent under a hostile WebContainer security policy completed the install with this wording and cited the bounding clauses as what lowered suspicion; all four refusal modes are now documented in the README. Fixes from the two field-test rounds: - guide: skip the ~90-line reference doc when the checklist is all green (point at `guide --full` instead), and note that claiming the site is the one manual action left so the ➜ line doesn't contradict "complete". - guide: bun-aware build wiring — `bun run` doesn't execute npm-style pre/post scripts, so the checklist suggests chaining scan/mark-build inside the build script on bun projects and counts that pattern as wired everywhere. AGENT-INSTALL documents the same. - AGENT-INSTALL: correct the "no env vars" trust claim (mark-build stamps hosting env variable *names*, never values — auditing agents caught the discrepancy), stop nudging agents to fetch install.txt remotely, and reconcile "run in order" with the checklist-first instruction. - guide: widget placement hint says "just before </body>". Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Guide flow enhancements include a dynamic checklist with full reference fallback. 🎯 Quality: 100% Elite · 📦 Size: Medium 📈 This month: Your 221st PR — above team average · Averaging Excellent |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A real-world agent refusal (WebContainer/Bolt-style) revealed a fourth refusal mode — unbounded "finish what the checklist marks missing" delegation plus a claim URL that reads as a machine-authorization link — so the README prompt is now a single line that bounds the delegation by naming the checklist's steps, states the claim URL is for the user to open in a browser, and links npmjs.com for verification; a simulated agent under a hostile WebContainer security policy completed the install with this wording and explicitly cited those clauses as what lowered suspicion.
The same field tests drove the code/doc fixes:
guideskips the ~90-line reference doc on all-green re-runs (--fullrestores it) and clarifies that claiming is the one manual action left; build wiring is bun-aware (bun doesn't run npm-style pre/post scripts, so the checklist suggests and recognizes chaining inside the build script); AGENT-INSTALL corrects the "no env vars" trust claim (mark-build stamps hosting env variable names, never values), stops nudging agents to fetch install.txt remotely, and reconciles "run in order" with checklist-first. All four refusal modes are documented in the README so the prompt doesn't get simplified back into a refusable shape.Test plan
npm run typecheckandnpm testgreen (145 tests, 4 new/updated intests/guide.test.ts).🤖 Generated with Claude Code