specs/010-email-patch-import/checklists/requirements.md

Ref: main   Size: 2.3 KiB

# Requirements Checklist: Email/Format-Patch Import

## Functional Requirements

- [x] **FR-001**: System MUST accept a file path argument pointing to a `.patch` file generated by `git format-patch`.
- [x] **FR-002**: System MUST parse the patch file to extract the commit message subject (title), body (description), and diff content.
- [x] **FR-003**: System MUST apply the patch to create a real git commit on a temporary branch (`collab/imported/<short-oid>`).
- [x] **FR-004**: System MUST create a patch DAG entry using the existing `patch::create()` function with the resulting commit OID.
- [x] **FR-005**: System MUST default `--base` to `main` if not specified.
- [x] **FR-006**: System MUST validate that the patch file is a valid `git format-patch` output before attempting to apply.
- [x] **FR-007**: System MUST NOT modify the working tree or current branch when importing a patch.
- [x] **FR-008**: System MUST report the created patch ID to stdout on success.
- [x] **FR-009**: System MUST exit with a non-zero status and descriptive error for malformed patches, missing files, apply conflicts, and missing base branches.
- [x] **FR-010**: System MUST support the `--series` flag for importing multiple patch files as a single patch DAG entry (P3).
- [x] **FR-011**: System MUST roll back any partially-applied commits if a series import fails partway through (P3).

## User Stories

- [x] **US-P1**: Import a .patch file and create patch DAG entry
- [x] **US-P2**: Review imported patches using existing review flow
- [x] **US-P3**: Multi-patch series import

## Edge Cases

- [x] **EC-001**: Patch file path does not exist
- [x] **EC-002**: Patch file is empty (0 bytes)
- [x] **EC-003**: Patch generated against a very different tree (conflicts)
- [x] **EC-004**: Same patch imported twice (two distinct DAG entries)
- [x] **EC-005**: Patch contains binary diffs
- [x] **EC-006**: Base branch does not exist
- [x] **EC-007**: Repository has uncommitted changes (no effect on import)

## Success Criteria

- [x] **SC-001**: End-to-end import-review-merge workflow works
- [x] **SC-002**: Error cases produce clear messages with no side effects
- [x] **SC-003**: Imported patches indistinguishable from local patches in list/show
- [x] **SC-004**: Multi-patch series import works (P3)
- [x] **SC-005**: All code passes cargo test and cargo clippy