[REVIEW] secure-code-review: add cryptographic agility migration gates

[yanziwei]

Problem

secure-code-review covers weak algorithms, CSPRNG use, key management, and TLS bypasses, but it does not ask reviewers to verify whether cryptographic code can be safely migrated when algorithms, key sizes, libraries, or compliance requirements change.

This leaves a practical review gap: applications may use acceptable algorithms today while still being brittle because ciphertexts, hashes, signatures, and tokens do not carry algorithm or key-version metadata, legacy fallback code is not time-bound, or migration jobs are untested.

Proposed improvement

Add a focused cryptographic agility section to Step 5 that requires reviewers to check:

• Algorithm IDs, key IDs, and version metadata on cryptographic artifacts.
• Centralized crypto policy instead of scattered hard-coded constants.
• Tested re-encryption, re-signing, password-hash upgrade, or token reissue paths.
• Time-bound legacy decrypt/verify compatibility windows.
• Fail-closed behavior for unknown algorithms, retired keys, malformed envelopes, and downgrade attempts.
• Test fixtures for old-format reads, new-format writes, mixed-version data, and migration idempotency.
• Telemetry proving how much legacy data remains before fallback code is removed.

This should be a documentation-only skill enhancement with no new tool permissions.

[JamesJi79]

VALID GAP: Cryptographic Agility Migration Gates

This is a valid false positive and a genuine coverage gap in the secure-code-review skill.

Why FP: The current secure-code-review skill checks point-in-time cryptographic posture (weak algorithms, CSPRNG, TLS bypasses, key management) but does not assess whether the codebase can survive a crypto migration. An application using acceptable algorithms today can still be brittle — ciphertexts without algorithm IDs cannot be re-encrypted at scale, tokens without key-version metadata cannot be reissued, and legacy fallback code without expiration dates becomes permanent tech debt.

Why Valid Gap: The proposal identifies seven actionable dimensions that reviewers currently have no guidance for:

1. Algorithm/key IDs on artifacts — without them, re-encryption is a blind guess across storage systems.
2. Centralized crypto policy — scattered constants are a migration nightmare vs. a single versioned policy layer.
3. Tested migration paths — re-encryption, re-signing, password-hash upgrade, and token reissue jobs need to exist and be tested before the migration deadline.
4. Time-bound fallback windows — legacy decrypt/verify compatibility must have a planned removal date or it becomes permanent.
5. Fail-closed on unknown algo/retired key — brittle code that crashes on unknown algorithm IDs is a production incident waiting to happen.
6. Test fixtures — old-format reads, new-format writes, mixed-version data, and migration idempotency are all distinct test scenarios not covered by existing guidance.
7. Migration telemetry — without knowing how much legacy data remains, teams cannot schedule fallback removal.

Scope: Documentation-only — no new tool permissions needed. Well-scoped enhancement that adds actionable review gates without scope creep.

[Dolpme]

Implemented in PR #1703: #1703