suaveplan/openspec/changes/archive/2026-05-03-crypto-spec-restore-versioning/tasks.md

1. Pre-flight validation

• 1.1 Confirm packages/crypto/crypto-keys/ does not exist on disk; confirm grep -rln "@suaveplan/crypto-keys" packages/ returns zero matches (excluding openspec/archive/)
• 1.2 Confirm packages/crypto/crypto/src/derivation/coordinate/coordinate.ts exports DerivationCoordinate carrying masterVersion and slotVersion
• 1.3 Confirm packages/crypto/crypto/src/derivation/layouts/layouts.ts exports DERIVATION_LAYOUT_V1 packing masterVersion u16 ‖ userId u32 ‖ depth u8 ‖ slotVersion u8
• 1.4 Confirm packages/crypto/crypto/src/wire-format/index.ts re-exports PUBLIC_BUNDLE_MAGIC, CHAIN_BUNDLE_MAGIC, KEY_SLOT_PRIVATE_BYTE_SIZE, KEY_SLOT_PUBLIC_BYTE_SIZE, V1_COORDINATE_BYTE_SIZE, *_FORMAT_VERSION
• 1.5 Run bunx turbo test --filter=@suaveplan/crypto and confirm green at HEAD

2. Verified-by pointer audit

• 2.1 For each Verified by: pointer in openspec/changes/crypto-spec-restore-versioning/specs/crypto/spec.md, parse out the <file-path>::"<test-name>" pair
• 2.2 For each pair, run grep -F "<test-name>" <file-path> and assert the test name string appears literally inside an it( or test( call site
• 2.3 Hard-fail this change if any pointer does not resolve. Adjust the spec text (rename scenario or pointer) and re-run until clean
• 2.4 Run bunx vitest run packages/crypto/crypto/src/keychain/keychain.test.ts packages/crypto/crypto/src/keychain/validity/validity.test.ts packages/crypto/crypto/src/keychain/key-slot/key-slot.test.ts packages/crypto/crypto/src/derivation/layouts/layouts.test.ts packages/crypto/crypto/src/derivation/coordinate/coordinate.test.ts packages/crypto/crypto/src/domain-tags/domain-tags.test.ts packages/crypto/crypto/src/bundles/public-bundle/public-bundle.test.ts packages/crypto/crypto/src/bundles/chain-bundle/chain-bundle.test.ts packages/crypto/crypto/src/authority/authority.test.ts packages/crypto/crypto/src/identity/identity.test.ts packages/crypto/crypto/src/revocation/revocation-list.test.ts packages/crypto/crypto/src/audit-log/audit-log.test.ts packages/crypto/crypto/src/packer/packer.test.ts packages/crypto/crypto/src/chunked-packer/chunked-packer.test.ts --reporter=verbose and confirm every test name cited in the spec passes (not skipped, not todo)

3. Symbol presence audit

• 3.1 Run grep -RnE "DERIVATION_LAYOUT_V1|DERIVATION_LAYOUT_V1_ID" packages/crypto/crypto/src/ and confirm at least one definition site
• 3.2 Run grep -RnE "PUBLIC_BUNDLE_MAGIC|CHAIN_BUNDLE_MAGIC|KEY_SLOT_PRIVATE_BYTE_SIZE|KEY_SLOT_PUBLIC_BYTE_SIZE|V1_COORDINATE_BYTE_SIZE|MAX_CHAIN_LINKS" packages/crypto/crypto/src/ and confirm definitions plus the wire-format barrel re-export
• 3.3 Run grep -RnE "DOMAIN_VAULT_V1|DOMAIN_PUBLIC_KEYCHAIN_V1|DOMAIN_PACKER_V1|DOMAIN_CHUNK_V1|DOMAIN_CRL_V1|DOMAIN_AUDIT_V1|DOMAIN_SLSA_BUILDER_V1|DOMAIN_BITPACKER_SIGNED_V1|DOMAIN_BITPACKER_HASHCHAIN_V1|DOMAIN_BITPACKER_MULTISIGN_V1" packages/crypto/crypto/src/domain-tags/ and confirm exactly the 10 v1 tags exist
• 3.4 Run grep -RnE "KEYCHAIN.UNKNOWN_LAYOUT|KEYCHAIN.LAYOUT_TOO_WIDE|KEYCHAIN.LAYOUT_ALREADY_REGISTERED|KEYCHAIN.NOT_YET_VALID|KEYCHAIN.EXPIRED|KEYCHAIN.UNKNOWN_PURPOSE|KEYCHAIN.SLOT_INVALID|AUTHORITY.DISPOSED|AUTHORITY.ABORTED|AUTHORITY.REVOKED" packages/crypto/crypto/src/errors/ and confirm every error code cited in the spec is defined

4. External-reference audit

• 4.1 Run grep -rln "@suaveplan/crypto-keys" packages/ scripts/ docs/ apps/ and confirm zero matches outside openspec/archive/
• 4.2 Run grep -rln "openspec/specs/crypto-keys" . and confirm zero matches outside openspec/changes/crypto-spec-restore-versioning/ and openspec/archive/
• 4.3 If any external reference is found, block the change and update the consumer to reference openspec/specs/crypto/ (the surface was folded into @suaveplan/crypto)

5. OpenSpec validation

• 5.1 Run bun openspec validate crypto-spec-restore-versioning --strict and confirm zero errors
• 5.2 Run bun openspec list and confirm crypto-spec-restore-versioning appears with tasks status reflecting current progress
• 5.3 Run bun openspec diff crypto-spec-restore-versioning and confirm it emits a sensible delta listing 13 added requirements on crypto and 5 removed requirements on crypto-keys

6. Apply the change

• 6.1 Run bun openspec apply crypto-spec-restore-versioning (or follow the equivalent manual fold per openspec/AGENTS.md): copy the 13 ADDED requirements from openspec/changes/crypto-spec-restore-versioning/specs/crypto/spec.md into openspec/specs/crypto/spec.md directly after the existing ### Requirement: deriveKeyFromPassword block; remove the entire openspec/specs/crypto-keys/ directory
• 6.2 Confirm openspec/specs/crypto-keys/ no longer exists on disk
• 6.3 Confirm openspec/specs/crypto/spec.md now contains the 13 new requirement headings exactly as authored

7. Post-apply validation

• 7.1 Run bun openspec validate --strict against the entire spec corpus and confirm zero errors
• 7.2 Run bunx turbo lint typecheck test --filter=@suaveplan/crypto and confirm green (this is a spec-only change but the package gate must remain green)
• 7.3 Run bunx turbo test:coverage --filter=@suaveplan/crypto and confirm 100% across statements / branches / functions / lines (no regression)
• 7.4 Run bun scripts/conformance/check-crypto-core-allowlist.ts and confirm 0 violations

8. Archive

• 8.1 Move openspec/changes/crypto-spec-restore-versioning/ to openspec/archive/<yyyy-mm-dd>-crypto-spec-restore-versioning/ per openspec/AGENTS.md
• 8.2 Confirm the archive contains proposal.md, design.md, tasks.md (with all checkboxes ticked), and specs/crypto/spec.md + specs/crypto-keys/spec.md
• 8.3 Update any tracker (STATUS.md, in-flight changes list) to reflect the archive
• 8.4 Commit the change in a single commit titled crypto-spec-restore-versioning: fold versioned-key vocabulary into live crypto spec