specs/001-gpg-event-signing/checklists/requirements.md

Ref: main   Size: 4.8 KiB

# Requirements Quality Checklist: Ed25519 Signing for Event Commits

**Purpose**: Validate specification completeness, clarity, and consistency for Ed25519 event signing
**Created**: 2026-03-21
**Feature**: [spec.md](../spec.md)

## Requirement Completeness

- [ ] CHK001 Are signing requirements defined for all event action types (IssueOpen, IssueComment, IssueClose, IssueEdit, IssueLabel, IssueUnlabel, IssueAssign, IssueUnassign, IssueReopen, PatchCreate, PatchRevise, PatchReview, PatchComment, PatchInlineComment, PatchClose, PatchMerge)? [Completeness, Spec §FR-001]
- [ ] CHK002 Are key storage path requirements specified with platform-specific fallbacks (XDG_CONFIG_HOME vs hardcoded ~/.config)? [Completeness, Spec §FR-006]
- [ ] CHK003 Are file permission requirements documented for both private key (0o600) and public key files? [Completeness, Gap]
- [ ] CHK004 Are requirements defined for what `collab init-key` outputs to the user? [Completeness, Spec §FR-006]
- [ ] CHK005 Are requirements specified for the `--force` flag behavior on `collab init-key` when a key already exists? [Completeness, Gap]

## Requirement Clarity

- [ ] CHK006 Is "canonical serialization" precisely defined — does it specify sorted keys, compact format, and encoding? [Clarity, Spec §FR-010]
- [ ] CHK007 Is the base64 encoding variant specified (standard vs URL-safe, with/without padding)? [Clarity, Spec §FR-009]
- [ ] CHK008 Is "clear, actionable error message" quantified with specific content requirements for missing-key errors? [Clarity, Spec §FR-005]
- [ ] CHK009 Is "unrecognized key" precisely defined — does it mean not in a local known-keys file, or just cryptographically unverifiable? [Clarity, Spec §FR-004]
- [ ] CHK010 Are the exact field names (`signature`, `pubkey`) and their position in the JSON structure specified? [Clarity, Spec §FR-009]

## Requirement Consistency

- [ ] CHK011 Is the feature branch name (`001-gpg-event-signing`) consistent with the Ed25519 direction, or does the GPG naming create confusion? [Consistency]
- [ ] CHK012 Are verification failure reasons consistent between FR-004 (reject categories) and FR-007 (reporting requirements)? [Consistency, Spec §FR-004/FR-007]
- [ ] CHK013 Are the Merge action signing requirements in FR-002 consistent with the Edge Cases section on unavailable secret keys? [Consistency, Spec §FR-002]

## Acceptance Criteria Quality

- [ ] CHK014 Can SC-004 ("no more than 1 second per 100 synced commits") be objectively measured with a specific benchmark methodology? [Measurability, Spec §SC-004]
- [ ] CHK015 Are acceptance scenarios defined for the `collab init-key` command? [Gap, Spec §FR-006]
- [ ] CHK016 Are acceptance scenarios defined for the `--force` overwrite case? [Gap]

## Scenario Coverage

- [ ] CHK017 Are requirements defined for what happens when a user runs `collab init-key` twice without `--force`? [Coverage, Exception Flow]
- [ ] CHK018 Are requirements specified for sync behavior when *some* refs pass verification and others fail? [Coverage, Spec §FR-008]
- [ ] CHK019 Are requirements defined for how existing unsigned events in a repo are handled on the *first* sync after adoption? [Coverage, Spec §FR-004a]
- [ ] CHK020 Are requirements specified for the interaction between signing and the TUI dashboard display? [Coverage, Gap]

## Edge Case Coverage

- [ ] CHK021 Are requirements defined for behavior when the private key file exists but is corrupted or has wrong format? [Edge Case, Gap]
- [ ] CHK022 Are requirements defined for behavior when the private key file has incorrect permissions (e.g., world-readable)? [Edge Case, Gap]
- [ ] CHK023 Are requirements defined for concurrent event creation (race condition on signing)? [Edge Case, Gap]
- [ ] CHK024 Are requirements defined for event.json files that contain extra unknown fields during verification? [Edge Case, Gap]

## Non-Functional Requirements

- [ ] CHK025 Are key generation entropy requirements specified (CSPRNG source)? [Security, Gap]
- [ ] CHK026 Are requirements defined for private key memory handling (zeroing after use)? [Security, Gap]
- [ ] CHK027 Are observability requirements defined for signing/verification operations (logging, metrics)? [Non-Functional, Gap]

## Dependencies & Assumptions

- [ ] CHK028 Is the assumption that "collaborators exchange public keys out-of-band" sufficient, or should a known-keys mechanism be specified? [Assumption, Spec §Assumptions]
- [ ] CHK029 Is the ed25519-dalek crate dependency assumption validated against the project's Rust edition and platform targets? [Dependency, Spec §Assumptions]

## Notes

- Focus: Security and cryptographic requirements quality
- Depth: Standard
- Audience: Reviewer (PR)
- 29 items total across 8 quality dimensions
- Items reference spec sections where applicable; [Gap] marks missing requirements