chore: inline details around exit codes

[thisislawatts]

Pull Request Submission Checklist

• Follows [CONTRIBUTING](https://github.com/snyk/cli/blob/main/CONTRIBUTING.md) guidelines
• Commit messages are release-note ready, emphasizing what was changed, not how.
• Includes detailed description of changes
• Contains risk assessment (Low | Medium | High)
• Highlights breaking API changes (if applicable)
• Links to automated tests covering new functionality
• Includes manual testing instructions (if necessary)
• Updates relevant GitBook documentation (PR link: ___)
• Includes product update to be announced in the next stable release notes

What does this PR do?

This PR introduces comprehensive inline documentation for the CLI exit code strategy. It establishes a formal "Source of Truth" within the codebase regarding the design philosophy, technical constraints (8-bit limits), and the nature of exit codes as a stable public API contract.

Key additions include:

• Rule of 1 Documentation: Emphasizing that exit codes should be categorical rather than granular.
• JSON-First Strategy: Documenting that granular error handling should happen via structured output, not exit codes.
• Safety Warnings: Explicitly documenting the 8-bit wrap-around behavior to prevent security-critical silent successes.
• Cross-referencing: Linking the constants package to the implementation logic in behavior.

Where should the reviewer start?

Start with cliv2/cmd/cliv2/behavior/maperrortoexitcode.go to review the design philosophy and constraints added to the MapErrorCatalogToExitCode function. Then verify the cross-reference in cliv2/internal/constants/constants.go.

How should this be manually tested?

This is a documentation-only change to existing files. Verify that the comments are correctly picked up by go doc:

go doc ./cmd/cliv2/behavior MapErrorCatalogToExitCode

What's the product update that needs to be communicated to CLI users?

No functional change to the product; this PR improves internal maintainability and contributor alignment with Snyk's public API stability standards.

Risk assessment (Low | Medium | High)?

Low. This PR adds documentation/comments only and does not modify the execution logic of the mapping function or the value of the constants.

Any background context you want to provide?

As the CLI matures, it is essential to prevent "exit code sprawl." By documenting that exit codes are a stable contract and suggesting JSON for granular details, we reduce the likelihood of accidental breaking changes and maintain a clean interface for CI/CD automation.

[github-actions]

	Warnings
⚠️	There are multiple commits on your branch, please squash them locally before merging!

Generated by 🚫 dangerJS against 24272e6