YK-22 (yubikey) chore(docs): record the hardware acceptance checklist run

Start with docs/hardware-checklist.md and research/05-testing-without-hardware.md, then review the YK-22 section in plan/yubikey-identity/issues/m5-hardware-gate-and-policy-lift.md. Run all 19 checklist items on both generated-on-card and imported keys, including the recovery drill, and record commands, results, version, platform, and measurements in plan/yubikey-identity/hardware-run-.md. Done means every acceptance criterion is discharged and the recurring recovery section is added.

Parent #62 · YubiKey identity M5 — The hardware gate and the policy lift

Plan (vault): 1.Projects/envelope/plan/yubikey-identity/issues/m5-hardware-gate-and-policy-lift.md §YK-22

Points: 1 (0.5 d) · Depends on: #81 (YK-19) · Parallel with: —

Context

A sanctioned non-code gate — one of exactly two in this plan, the other being YK-01. It is a gate rather than a docs issue because the deliverable is evidence: the nine claims graded [dev] in the PRD exist nowhere else in the plan and no code branches on one, so the only way to discharge them is to run the pipeline against a real device and write down what happened.

docs/hardware-checklist.md already exists and holds all 19 items by the time this issue starts — each was appended by the issue whose behaviour it proves (items 1 and 12 by YK-07, 2/3/4/11 by YK-14, 5 by YK-16, 6/7/9 by YK-15, 8 by YK-19, 10 by YK-08, 13 by YK-13, 14 and 17 by YK-10, 15 by YK-05, 16 by YK-17, 18 by YK-06, 19 by YK-01). This issue executes it.

Anything that fails is a blocker, not a note. A surprise in the ykman piv reset semantics — the custody note's central claim, which the plugin's own repository does not corroborate — affects the recovery obligation and the docs, not a code path, so it rewrites YK-14's and YK-23's prose and blocks nothing in M0–M4. A surprise in the prompt counts, the mixed-set round trip or the replacement drill is a design failure and must be treated as one.

Scope

Code — none. This is the gate.

Tests — none automated. The checklist is the test, and its 19 items are the assertions. Two of them re-confirm on a device what the research settled by source read, and they are the cheap ones worth doing first: item 1 (the mixed-set round trip, which turns OQ-3 from a source read into a measurement) and item 8 (the interaction counts, which turn architecture §6.3 from a model into a measurement).

Docs — execute the checklist once, on both a generated-on-card key and an imported key, and record the results in this plan folder as hardware-run-<YYYYMMDD>.md:

• the per-key setup record item 2 asks for: model, firmware, serial, retired slot, generated-on-card vs imported, PIN and touch policies;
• the exact age-plugin-yubikey version and platform the run was made on — recorded so a future divergence is attributable, and so YK-14's install-channel prose can name the version it was validated against;
• for each of the 19 items: pass/fail, the command run, and the observed output where it differs from the expectation;
• the measured prompt and touch counts for split / verify / restore, including a verify over two -in directories, against architecture §6.3 — plus how often the 15-second TouchPolicy::Cached wall-clock window lapsed while reading cold USB media, which is the caveat NFR-YK-03 states but cannot measure;
• the answer to item 9's open question — whether the v0.5.1 Linux artifact gap is a failed CI job or intentional — which affects docs/usage.md's wording only, and any correction it implies for YK-07's install section.

Also append to docs/hardware-checklist.md, in a "Recurring — every six months" section: the recovery drill as numbered steps with expected output (the other half of the retired YK-25). It belongs here and not in YK-14's bind reference because it is a recurring procedure, it is executed exactly as the one-time items are, and this issue's own run is its first recorded execution — checklist item 11 is the drill. The steps: confirm the bundle's mac-key-id matches the backup (no card needed), restore a known shard set with the backup identity alone and confirm the note names it, re-bind -replace-identity against a stub regenerated from the imported key, and re-verify. Record the run in the same hardware-run-<YYYYMMDD>.md file.

Acceptance criteria

• All 19 items of docs/hardware-checklist.md executed, on a generated-on-card key and on an imported key, with results recorded in plan/yubikey-identity/hardware-run-<YYYYMMDD>.md.
• Exit criterion 1 discharged: bind, split a ≥ 1 MiB file at (3,5), delete two shards, restore, cmp identical — on both key kinds.
• Exit criterion 2 discharged: with every card unplugged, split encrypts the payload and stops only at the pin unwrap, with a card-required diagnosis.
• Exit criterion 3 discharged: a (3,5) set split to [YK1, YK2, offline paper identity] restores from each of the three independently, with the other two absent, and the absent keys' PINs are never requested.
• Exit criterion 4 discharged: a backed-up P-256 key imported into a second YubiKey yields a byte-identical recipient; after bind -replace-identity, an existing shard set restores with no re-encryption.
• Exit criterion 5 discharged: after ykman piv reset on a spare key, restore and verify fail closed with a named diagnosis and write nothing. The reset semantics themselves are validated here or nowhere.
• Exit criterion 6 discharged: architecture §6.3's counts confirmed on a PinPolicy::Once + TouchPolicy::Cached device, including a verify over two -in directories.
• Exit criterion 9 discharged: over a marker-bearing input with a real PIN, the marker and the PIN appear in no shard, no stream, no log and no CI artifact.
• Exit criterion 10 discharged: CI green without hardware, and the checklist executed and recorded.
• docs/hardware-checklist.md gains a "Recurring — every six months" section holding the recovery drill as numbered steps with expected output, and this run is recorded as its first execution.
• The age-plugin-yubikey version and platform are recorded; any correction to YK-07's install prose or YK-14's policy prose is filed as a follow-up commit before YK-23.
• Every failure is treated as a blocker: no item is recorded as "passed with a note".

Out of scope

The README policy sentence — YK-23, gated on this. Any code change: if an item fails, the fix is its own issue on its own branch, and this gate is re-run.

Risks and notes

• ykman piv reset is the one claim with no corroboration. The custody note says it needs no PIN, PUK or management key, burns the retry counters and resets the applet; the plugin's own repository documents no reset or recovery procedure at all. Verify it on a spare key, and if it is wrong in the safer direction the recovery obligation in YK-14 and YK-23 gets weaker, not the code.
• Imported keys prompt more, not less. An imported key cannot satisfy attestation, so the plugin reads neither policy and always requests a PIN. Expect the recoverable configuration to be the noisier one and do not treat that as a failure.
• Upstream #241 strikes during setup, not use: an unsupported-algorithm key in any enumerated PIV slot breaks --list / --generate / --identity on v0.5.1 while decryption keeps working. If setup fails oddly, check the other slots before suspecting Envelope.

References

FR-YK-15 (gate half) · exit criteria 1–6, 9, 10 · architecture §6.3, §10 · the 19 items drafted in research/05-testing-without-hardware.md §"Manual hardware acceptance checklist" · research/00-overview.md §"Residual unknowns that need a real device"