[davidchaiken]

Summary

This is the second of two pull requests for milestone 1, slice 6, and it closes milestone 1 (DEVELOPMENT-PLAN.md). It adds the debugging guide, docs/debugging.md, which REQUIREMENTS §6 counts as documented only once it has been run end to end. The maintainer ran it on 2026-11-11, on macOS with VS Code and CodeLLDB. With it, ARCHITECTURE §10 [G1] is closed, and every item milestone 1 closes ([S3]–[S7], [G1]) is struck.

Changes

• docs/debugging.md, linked from the README:
  • versions known to work, each with the command or place that shows it;
  • the two launch configurations;
  • a first session, at exit_code;
  • where to break: four tables by phase, each row with an input, the function, and what to look at;
  • what the debugger shows, including every claim value in cleartext, which every output masks;
  • debugging tests;
  • checking vcrd's results without a debugger.
• scripts/debugging/: five bash helper scripts, using the base64, jq, bc, xxd and openssl on PATH. The guide quotes each in full.
  • jws-decode.sh prints a compact JWS's header and payload, with a warning on standard error that claim values are not masked.
  • did-key-jwk.sh prints an Ed25519 did:key's JWK.
  • jwk-thumbprint.sh prints a JWK's RFC 7638 thumbprint.
  • b64url-decode.sh and b64url-encode.sh are shared by the others.
• vcrd-cli/tests/debugging.rs: three new checks.
  • Each function in the guide's "Where to break" tables is defined in the file named.
  • Each repository path the guide names exists.
  • Each helper script is quoted verbatim in the guide.
• docs/reviews/milestone-1.md: round 8, the guide's run, what it changed in the guide, and checks R42–R45.
• ARCHITECTURE §10: [G1] struck.
• DEVELOPMENT-PLAN.md, milestone 2: a task to move the toolchain pin to Rust 1.101 when it is stable (scheduled for 2026-12-24) and run the guide again on macOS.

Test plan

• make ci-ok passed on e35e4ef.
• make test-powerset passed (Every build passed., exit 0).
• The guide was run end to end on 2026-11-11 (docs/reviews/milestone-1.md, "The debugging guide"). The helper scripts give the same JWK and thumbprints as vcrd's key_provenance, and the thumbprint of RFC 8037 Appendix A.3, with both OpenSSL 3.6.3 and LibreSSL 3.3.6.
• Checks R42–R45 in docs/reviews/milestone-1.md, each shown failing on a planted fault before it passed.

🤖 Generated with Claude Code using Opus 5.5 - Extra effort

[davidchaiken]

I ran everything in the debugging guide and provided multiple rounds of feedback on the content.