# application-archiving Specification

## Purpose
Provide a structured way to archive job applications that are no longer active, maintaining organization and preserving all application work. This capability enables users to move applications from `applications/pending/` to outcome-specific folders (`rejected`, `not-interested`) with metadata updates and safety protections.

## ADDED Requirements

### Requirement: Application Archiving Command

The system SHALL provide a `/archive-application` command that moves applications from pending to archive folders with metadata updates.

#### Scenario: Archive rejected application from current directory

- **WHEN** user navigates to `applications/pending/[folder]/` and runs `/archive-application rejected`
- **THEN** system detects current application automatically
- **AND** moves application folder from `applications/pending/` to `applications/rejected/`
- **AND** updates Status field to "Rejected (Archived: [timestamp])"
- **AND** preserves all files and folders (application.md, input/, attachments/)
- **AND** shows success message with archive location

#### Scenario: Archive not-interested application by name

- **WHEN** user runs `/archive-application not-interested 2025-11-02-TechCorp-Developer` from any location
- **THEN** system resolves application path in pending folder
- **AND** moves application to `applications/not-interested/`
- **AND** updates Status field to "Not Interested (Archived: [timestamp])"
- **AND** shows success message with original and new locations

#### Scenario: Display help information

- **WHEN** user runs `/archive-application --help`
- **THEN** system displays command syntax and usage information
- **AND** explains parameters (reason, application-name, flags)
- **AND** provides examples for common scenarios
- **AND** describes what happens during archiving

#### Scenario: Validate reason parameter

- **WHEN** user provides invalid reason (not "rejected" or "not-interested")
- **THEN** system shows error message listing valid reasons
- **AND** displays usage information
- **AND** does NOT modify any files

#### Scenario: Resolve application location

- **WHEN** user provides application name without full path
- **THEN** system searches `applications/pending/` for matching folder
- **AND** resolves to full path if found
- **AND** shows error if application not found
- **AND** lists available applications in pending folder

---

### Requirement: Safety Warnings for Generated Documents

The system SHALL warn users before archiving applications with generated documents to prevent accidental loss of work.

#### Scenario: Detect and warn about cover letter

- **WHEN** application folder contains `cover-letter.md`
- **THEN** system displays warning message
- **AND** lists cover-letter.md as generated document
- **AND** stops archiving process
- **AND** requires `--force` flag to proceed

#### Scenario: Detect and warn about application email

- **WHEN** application folder contains `application-email.md`
- **THEN** system displays warning message
- **AND** lists application-email.md as generated document
- **AND** stops archiving process
- **AND** requires `--force` flag to proceed

#### Scenario: Detect and warn about attachments

- **WHEN** `attachments/` folder contains files (excluding `.keep`)
- **THEN** system displays warning message
- **AND** shows count of files in attachments folder
- **AND** stops archiving process
- **AND** requires `--force` flag to proceed

#### Scenario: Warning message provides clear options

- **WHEN** safety warning is displayed
- **THEN** message lists all detected documents
- **AND** explains that archiving will move everything
- **AND** provides three options: continue with --force, cancel to review, or backup first
- **AND** shows exact command to use with --force flag

#### Scenario: Force flag bypasses all warnings

- **WHEN** user provides `--force` flag
- **THEN** system skips all safety checks
- **AND** proceeds with archiving without warnings
- **AND** shows brief notice that --force was used
- **AND** completes archiving successfully

#### Scenario: No warning for empty attachments folder

- **WHEN** `attachments/` folder exists but only contains `.keep` file
- **THEN** system does NOT treat this as "having attachments"
- **AND** does NOT display warning about attachments
- **AND** proceeds with archiving (if no other documents found)

---

### Requirement: Status and Timestamp Tracking

The system SHALL update application metadata when archiving to maintain audit trail and lifecycle tracking.

#### Scenario: Update Status field for rejected application

- **WHEN** application is archived with reason "rejected"
- **THEN** system reads `application.md` file
- **AND** locates Status field in Metadata section
- **AND** replaces Status line with: `- **Status**: Rejected (Archived: YYYY-MM-DD HH:MM)`
- **AND** writes updated content back to file
- **AND** preserves all other content in application.md

#### Scenario: Update Status field for not-interested application

- **WHEN** application is archived with reason "not-interested"
- **THEN** system reads `application.md` file
- **AND** locates Status field in Metadata section
- **AND** replaces Status line with: `- **Status**: Not Interested (Archived: YYYY-MM-DD HH:MM)`
- **AND** writes updated content back to file
- **AND** preserves all other content in application.md

#### Scenario: Handle missing Status field

- **WHEN** application.md does not have Status field in Metadata section
- **THEN** system adds Status field to Metadata section
- **AND** sets Status to appropriate archived value with timestamp
- **AND** preserves existing Metadata section formatting
- **AND** proceeds with archiving

#### Scenario: Timestamp format

- **WHEN** Status field is updated with timestamp
- **THEN** timestamp follows format: YYYY-MM-DD HH:MM
- **AND** uses current date and time at moment of archiving
- **AND** uses 24-hour time format
- **AND** is human-readable and sortable

#### Scenario: Status update failure handling

- **WHEN** Status field update fails (file locked, permissions error)
- **THEN** system stops archiving process
- **AND** shows error message with details
- **AND** does NOT move application folder
- **AND** leaves application in pending folder unchanged

---

### Requirement: Archive Folder Structure

The system SHALL maintain organized archive folders by reason while preserving application structure.

#### Scenario: Create rejected archive folder on first use

- **WHEN** user archives first application with reason "rejected"
- **AND** `applications/rejected/` folder does not exist
- **THEN** system creates `applications/rejected/` directory
- **AND** shows progress message: "Created archive directory: applications/rejected/"
- **AND** proceeds with archiving to new folder

#### Scenario: Create not-interested archive folder on first use

- **WHEN** user archives first application with reason "not-interested"
- **AND** `applications/not-interested/` folder does not exist
- **THEN** system creates `applications/not-interested/` directory
- **AND** shows progress message: "Created archive directory: applications/not-interested/"
- **AND** proceeds with archiving to new folder

#### Scenario: Preserve folder naming convention

- **WHEN** application is moved to archive
- **THEN** folder name remains unchanged (YYYY-MM-DD-Company-JobTitle format)
- **AND** application is placed in `applications/[reason]/[original-folder-name]/`
- **AND** date prefix is preserved for chronological sorting

#### Scenario: Preserve application structure

- **WHEN** application folder is moved to archive
- **THEN** all subfolders are preserved (input/, attachments/)
- **AND** all files are preserved (application.md, cover-letter.md, application-email.md)
- **AND** folder structure remains identical to pending folder structure
- **AND** no files are modified except application.md Status field

#### Scenario: Verify successful move

- **WHEN** move operation completes
- **THEN** system verifies destination folder exists: `applications/[reason]/[folder]/`
- **AND** verifies source folder no longer exists: `applications/pending/[folder]/`
- **AND** verifies application.md exists at destination
- **AND** only shows success message after verification passes

---

### Requirement: Comprehensive Error Handling

The system SHALL provide clear, actionable error messages for all failure scenarios.

#### Scenario: Invalid reason parameter error

- **WHEN** user provides unsupported reason (not "rejected" or "not-interested")
- **THEN** system displays error message: "Invalid reason: [provided-reason]"
- **AND** lists valid options: rejected, not-interested
- **AND** explains what each reason means
- **AND** shows usage syntax

#### Scenario: Application not found error

- **WHEN** user provides application name that doesn't exist in pending
- **THEN** system displays error message: "Application not found: [application-name]"
- **AND** lists all available applications in `applications/pending/`
- **AND** shows usage syntax with application name parameter

#### Scenario: Not in application folder error

- **WHEN** user runs command without application name parameter
- **AND** current directory is not within an application folder
- **THEN** system displays error message: "Not in an application folder"
- **AND** explains two options: navigate to application folder, or provide application name
- **AND** lists available applications in pending folder
- **AND** shows example commands for both approaches

#### Scenario: Already archived error

- **WHEN** user tries to archive application that doesn't exist in pending
- **THEN** system displays error message: "Application not found in pending folder"
- **AND** suggests checking archive folders (rejected/, not-interested/)
- **AND** explains how to move between archives if needed
- **AND** does NOT show pending applications list (not relevant)

#### Scenario: File operation failure error

- **WHEN** move operation fails (permissions, disk space, concurrent access)
- **THEN** system displays error message: "Failed to archive application"
- **AND** includes specific error details from file system
- **AND** lists possible causes (permissions, disk space, file in use)
- **AND** confirms: "The application has NOT been modified"
- **AND** suggests checking the issue and trying again

#### Scenario: Permission denied error

- **WHEN** user lacks permissions to write to application.md or move folder
- **THEN** system displays error about insufficient permissions
- **AND** explains which operation failed (status update or folder move)
- **AND** suggests checking file/folder permissions
- **AND** ensures no partial changes (rollback any modifications)

---

### Requirement: Auto-Detection of Application Location

The system SHALL automatically detect the target application when run from within an application folder.

#### Scenario: Detect application from current directory

- **WHEN** user is in directory matching pattern `*/applications/pending/[folder-name]/`
- **AND** current directory contains `application.md` file
- **THEN** system automatically detects application to archive
- **AND** extracts folder name for use in move operation
- **AND** does NOT require application name parameter

#### Scenario: Verify application.md exists

- **WHEN** system detects application from current directory
- **THEN** system verifies `application.md` file exists
- **AND** shows error if application.md missing
- **AND** explains that directory doesn't appear to be valid application folder

#### Scenario: Handle subdirectories within application

- **WHEN** user is in subdirectory like `*/applications/pending/[folder]/input/`
- **THEN** system detects parent application folder
- **AND** resolves to correct application path
- **AND** proceeds with archiving parent application

#### Scenario: Explicit name overrides auto-detection

- **WHEN** user provides application name parameter
- **THEN** system uses provided name instead of auto-detecting
- **AND** ignores current directory location
- **AND** resolves to specified application in pending folder

---

### Requirement: Success Messaging and Confirmation

The system SHALL provide clear confirmation when archiving succeeds with relevant details.

#### Scenario: Display success message with details

- **WHEN** archiving completes successfully
- **THEN** system displays success message: "Application archived successfully"
- **AND** shows application name (Company - Job Title)
- **AND** shows original location: `applications/pending/[folder]/`
- **AND** shows archived location: `applications/[reason]/[folder]/`
- **AND** shows reason: "Rejected by company" or "No longer interested"
- **AND** shows updated Status: "Rejected (Archived: [timestamp])"

#### Scenario: Confirm preservation of all files

- **WHEN** success message is displayed
- **THEN** message confirms: "All documents intact"
- **AND** explains application can still be accessed at new location
- **AND** provides full path to archived application

#### Scenario: Success with --force flag

- **WHEN** archiving completes with --force flag
- **THEN** success message includes note: "Safety checks skipped (--force)"
- **AND** lists which documents were detected but bypassed
- **AND** confirms all documents were moved to archive

---

## Cross-References

### Related Capabilities

- **application-management**: Archiving is the final step in application lifecycle
- **application-validation**: Validation ensures applications are complete before potential archiving
- **cover-letter-generation**: Generated cover letters trigger safety warnings when archiving
- **application-email**: Generated emails trigger safety warnings when archiving

### Integration Points

- Status field in `application.md` (managed by application-management)
- Application folder structure (defined by application-management)
- Generated document detection (cover-letter.md, application-email.md)
- Attachments folder (created by application-management)

---

## Technical Notes

### Status Field Update Implementation

**Pattern matching:**
```regex
^(\s*-\s*\*\*Status\*\*:\s*)(.*)$
```

**Replacement format:**
```markdown
- **Status**: [Rejected|Not Interested] (Archived: YYYY-MM-DD HH:MM)
```

### Safety Check Detection

**Files to check:**
1. `cover-letter.md` in application folder
2. `application-email.md` in application folder
3. Any files in `attachments/` excluding `.keep`

**Warning triggered if ANY found**

### Archive Folder Paths

- Rejected: `src/applications/rejected/`
- Not interested: `src/applications/not-interested/`

**Folders created on-demand when first needed**

---

## Validation

This specification can be validated by:

1. Running `openspec validate archive-applications --strict`
2. Verifying all requirements have at least one scenario
3. Checking all scenarios follow WHEN/THEN/AND format
4. Confirming no placeholder text remains in requirements