[PR] docs(setup): touch the hardware key for signatures, not for ssh transport [magpie]

["potiuk (via GitHub)" <gi...@apache.org>]

potiuk opened a new pull request, #1367:
URL: https://github.com/apache/magpie/pull/1367

   ## 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 #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
   
   - [x] Skill change (`.claude/skills/<name>/`) — eval fixtures updated below
   - [ ] Tool / bridge contract (`tools/<system>/*.md`)
   - [ ] Python package (`tools/*/` with `pyproject.toml`)
   - [ ] Groovy reference impl
   - [x] Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
   - [x] 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
   
   - [x] `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
   - [x] 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
   - [x] 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
   
   - [x] **HITL** — `ykman` commands are still handed to the operator; the skill never runs them
   - [x] **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 #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](https://claude.com/claude-code)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs(setup): touch the hardware key for signatures, not for ssh transport [magpie]

["potiuk (via GitHub)" <gi...@apache.org>]

potiuk merged PR #1367:
URL: https://github.com/apache/magpie/pull/1367


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org