docs(setup): touch the hardware key for signatures, not for ssh transport

[potiuk]

Summary

• The secure setup recommended a cached touch policy on both the signing (sig) and the ssh authentication (aut) slot of a hardware key, so every git fetch, git pull and git push waited for a touch. Fetch and pull are reads; a push is already confirmed by the git push ask rule and can only carry commits that were signed with a touch. The transport touch was a prompt that bought no control — the prompt-fatigue case the proposed principle in principles: add "Avoiding prompt fatigue" as §1, ahead of the security principle (PMC vote required) #1291 describes.
• New recommendation: sig cached, aut off. The touch stays on every signature and leaves the transport.
• Exception: with gpg.format=ssh the signature is made by the aut key, and the card cannot tell a signature from a login, so aut must stay cached there. The docs say so and name the two ways out (OpenPGP signing, or an https remote).

Type of change

• Skill change (.claude/skills/<name>/) — eval fixtures updated below
• Tool / bridge contract (tools/<system>/*.md)
• Python package (tools/*/ with pyproject.toml)
• Groovy reference impl
• Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
• Documentation (docs/, README.md, CONTRIBUTING.md)
• Project template (projects/_template/)
• CI / dev loop (prek, workflows, validators)
• Other:

What changed:

• docs/setup/secure-agent-setup.md — rationale, ykman commands, OpenPGP as the recommended signing form, the gpg.format=ssh caveat, the install / verify walk-throughs and the overlay test.
• docs/rfcs/RFC-AI-0002.md Layer 3b — the touch covers signatures, not the transport (heading kept, so existing anchors still resolve).
• docs/setup/sandbox-troubleshooting.md — the transport-touch hang applies only when aut carries a policy.
• setup-isolated-setup-install step K.1 — proposes the touch on whichever slot signs (from gpg.format), and aut off for OpenPGP signers whose aut carries a policy.
• setup-isolated-setup-verify check 10 — same rule.

Test plan

• prek run on every changed file passes (including check-doc-sync and lychee)
• For Python packages touched: n/a
• For Groovy bridges touched: n/a
• For skill changes: eval suite for step-hardware-key graded by agent self-eval against the new K.1 text — all four cases match; a cross-model --cli run is still to do
• For skill behaviour changes: new fixture case-4-openpgp-aut-cached (OpenPGP signer with aut cached → aut off proposed); new slots_to_clear output field; case-2 renamed to case-2-ssh-signing-aut-cached with its expectation corrected (ssh signing, aut already cached → no change); case-3 now expects sig only
• Other:

RFC-AI-0004 compliance

• HITL — ykman commands are still handed to the operator; the skill never runs them
• Sandbox — no new host access; the sandbox grants are unchanged
• Vendor neutrality
• Conversational + correctable
• Write-access discipline
• Privacy LLM

Linked issues

Refs #1291

Notes for reviewers (optional)

• The new text points at PRINCIPLES.md §1 as the prompt-fatigue principle. That is true only once principles: add "Avoiding prompt fatigue" as §1, ahead of the security principle (PMC vote required) #1291 merges, so this PR should merge after it.
• This moves a physical control off git push. The argument is that the push is still gated twice without it (the permissions.ask rule, and the signature touch on every commit it carries); worth a critical read if you disagree.

---

Generated-by: Claude Opus 5

🤖 Generated with Claude Code