docs(02-02): complete archive commands plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/REQUIREMENTS.md

@@ -37,8 +37,8 @@
 ### CLI Archiver (Архиватор)
 
 - [x] **CLI-01**: Rust CLI утилита для создания архивов (Linux/macOS)
-- [ ] **CLI-02**: Упаковка нескольких файлов (тексты + APK) в один архив
-- [ ] **CLI-03**: Подкоманды: pack, unpack (для тестирования), inspect (для отладки)
+- [x] **CLI-02**: Упаковка нескольких файлов (тексты + APK) в один архив
+- [x] **CLI-03**: Подкоманды: pack, unpack (для тестирования), inspect (для отладки)
 
 ### Kotlin Decoder (Kotlin декодер)
 
@@ -111,8 +111,8 @@
 | INT-01 | Phase 2 | Complete |
 | INT-02 | Phase 3 | Pending |
 | CLI-01 | Phase 2 | Complete |
-| CLI-02 | Phase 2 | Pending |
-| CLI-03 | Phase 2 | Pending |
+| CLI-02 | Phase 2 | Complete |
+| CLI-03 | Phase 2 | Complete |
 | KOT-01 | Phase 4 | Pending |
 | KOT-02 | Phase 4 | Pending |
 | KOT-03 | Phase 4 | Pending |

.planning/ROADMAP.md

@@ -13,7 +13,7 @@ Build a custom encrypted archive format that standard tools cannot recognize or
 Decimal phases appear between their surrounding integers in numeric order.
 
 - [x] **Phase 1: Format Specification** - Document the complete binary format before writing any code (completed 2026-02-24)
-- [ ] **Phase 2: Core Archiver** - Rust CLI that compresses, encrypts, and packs files into the custom format
+- [x] **Phase 2: Core Archiver** - Rust CLI that compresses, encrypts, and packs files into the custom format (completed 2026-02-24)
 - [ ] **Phase 3: Round-Trip Verification** - Rust unpack command + golden test vectors + unit tests proving byte-identical round-trips
 - [ ] **Phase 4: Kotlin Decoder** - Android 13 decoder using javax.crypto and java.util.zip (primary extraction path)
 - [ ] **Phase 5: Shell Decoder** - Busybox shell script decoder using dd/xxd/openssl/gunzip (fallback extraction)
@@ -48,8 +48,8 @@ Plans:
 **Plans**: 2 plans
 
 Plans:
-- [ ] 02-01-PLAN.md -- Project scaffolding, binary format types, crypto pipeline, and compression module
-- [ ] 02-02-PLAN.md -- Pack, inspect, and unpack commands with full archive orchestration
+- [x] 02-01-PLAN.md -- Project scaffolding, binary format types, crypto pipeline, and compression module
+- [x] 02-02-PLAN.md -- Pack, inspect, and unpack commands with full archive orchestration
 
 ### Phase 3: Round-Trip Verification
 **Goal**: Proven byte-identical round-trips through the Rust unpack command, backed by golden test vectors
@@ -115,7 +115,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
 | 1. Format Specification | 1/1 | Complete    | 2026-02-24 |
-| 2. Core Archiver | 1/2 | In Progress | - |
+| 2. Core Archiver | 2/2 | Complete    | 2026-02-24 |
 | 3. Round-Trip Verification | 0/2 | Not started | - |
 | 4. Kotlin Decoder | 0/1 | Not started | - |
 | 5. Shell Decoder | 0/1 | Not started | - |

.planning/STATE.md

@@ -9,18 +9,18 @@ See: .planning/PROJECT.md (updated 2026-02-24)
 
 ## Current Position
 
-Phase: 2 of 6 (Core Archiver) -- IN PROGRESS
-Plan: 1 of 2 in current phase -- COMPLETE
-Status: Plan 02-01 complete, ready for Plan 02-02
-Last activity: 2026-02-24 -- Project foundation with crypto pipeline
+Phase: 2 of 6 (Core Archiver) -- COMPLETE
+Plan: 2 of 2 in current phase -- COMPLETE
+Status: Phase 2 complete, ready for Phase 3
+Last activity: 2026-02-24 -- Pack/unpack/inspect archive commands
 
-Progress: [██░░░░░░░░] 25%
+Progress: [███░░░░░░░] 33%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 2
-- Average duration: 5.5 min
+- Total plans completed: 3
+- Average duration: 4.3 min
 - Total execution time: 0.2 hours
 
 **By Phase:**
@@ -28,10 +28,10 @@ Progress: [██░░░░░░░░] 25%
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
 | 1. Format Specification | 1 | 7 min | 7 min |
-| 2. Core Archiver | 1/2 | 4 min | 4 min |
+| 2. Core Archiver | 2/2 | 6 min | 3 min |
 
 **Recent Trend:**
-- Last 5 plans: 7min, 4min
+- Last 5 plans: 7min, 4min, 2min
 - Trend: improving
 
 *Updated after each plan completion*
@@ -51,6 +51,9 @@ Recent decisions affecting current work:
 - Phase 1: HMAC scope = IV (16 bytes) || ciphertext (encrypted_size bytes)
 - Phase 2: Used rand::Fill::fill() for IV generation (correct rand 0.9 API)
 - Phase 2: Manual binary serialization with to_le_bytes/from_le_bytes (no serde/bincode)
+- Phase 2: Filename-only entry names (not full paths) for archive portability
+- Phase 2: HMAC failure skips file and continues; SHA-256 mismatch warns but writes
+- Phase 2: Flags bit 0 set only when at least one file is actually compressed
 
 ### Pending Todos
 
@@ -65,5 +68,5 @@ None yet.
 ## Session Continuity
 
 Last session: 2026-02-24
-Stopped at: Completed 02-01-PLAN.md (Project foundation with crypto pipeline)
+Stopped at: Completed 02-02-PLAN.md (Pack/unpack/inspect archive commands)
 Resume file: None

.planning/phases/02-core-archiver/02-02-SUMMARY.md

@@ -0,0 +1,107 @@
+---
+phase: 02-core-archiver
+plan: 02
+subsystem: archive, cli
+tags: [aes-256-cbc, hmac-sha256, gzip, binary-format, pack, unpack, inspect, encrypt-then-mac]
+
+# Dependency graph
+requires:
+  - phase: 02-core-archiver
+    plan: 01
+    provides: "Crypto pipeline (encrypt/decrypt/HMAC/SHA-256), format types (Header/TocEntry serialization), compression (gzip/heuristic), CLI skeleton, hardcoded key"
+provides:
+  - "pack() function: two-pass archive writer producing FORMAT.md-compliant archives"
+  - "unpack() function: HMAC-first verification, AES-256-CBC decryption, optional gzip decompression, SHA-256 integrity check"
+  - "inspect() function: metadata display (sizes, offsets, IVs, HMACs, SHA-256) without decryption"
+  - "CLI dispatch wiring all three commands to archive module"
+  - "Directory traversal protection in unpack"
+affects: [03-round-trip-verification, 04-kotlin-decoder, 05-shell-decoder, 06-obfuscation]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [two-pass archive writing (process then compute offsets), HMAC-before-decrypt verification order, filename-only entry names from full paths]
+
+key-files:
+  created: []
+  modified:
+    - src/archive.rs
+    - src/main.rs
+
+key-decisions:
+  - "Use filename-only (not full path) as archive entry name to keep entries portable"
+  - "Directory traversal protection: reject names starting with / or containing .."
+  - "HMAC failure skips file and continues; SHA-256 mismatch warns but still writes file"
+  - "Flags byte bit 0 set only when at least one file is actually compressed"
+
+patterns-established:
+  - "Two-pass archive writing: Pass 1 processes files in memory, Pass 2 computes offsets and writes sequentially"
+  - "HMAC verified before decryption attempt (encrypt-then-MAC per FORMAT.md Section 10)"
+  - "Per-file error handling: HMAC/SHA-256 failures increment error count, non-zero exit on any errors"
+  - "Inline TOC size computation: sum of (101 + name.len()) per file"
+
+requirements-completed: [CLI-02, CLI-03]
+
+# Metrics
+duration: 2min
+completed: 2026-02-24
+---
+
+# Phase 2 Plan 2: Archive Commands Summary
+
+**Pack/unpack/inspect commands with AES-256-CBC encryption, HMAC-SHA-256 verification, gzip compression, and FORMAT.md-compliant binary output**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-02-24T21:01:22Z
+- **Completed:** 2026-02-24T21:03:40Z
+- **Tasks:** 1
+- **Files modified:** 2
+
+## Accomplishments
+- Fully functional `encrypted_archive` binary with pack, unpack, and inspect commands
+- Round-trip verified: packed files are byte-identical after unpacking (text + binary)
+- HMAC tamper detection verified: flipping a ciphertext byte triggers rejection with non-zero exit
+- Compression auto-detection verified: .apk files stored without gzip (compression_flag=0, flags=0x00)
+- Archive starts with magic bytes 0x00 0xEA 0x72 0x63 (not recognized as any standard format)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Implement pack, inspect, unpack commands and wire CLI** - `be50707` (feat)
+
+## Files Created/Modified
+- `src/archive.rs` - Pack, unpack, and inspect orchestration (237 lines): two-pass pack writer, HMAC-first unpack, metadata inspect
+- `src/main.rs` - CLI dispatch wiring Commands enum to archive::pack/unpack/inspect
+
+## Decisions Made
+- **Filename-only entries:** Archive stores only the filename (not the full path) for portability across systems
+- **Directory traversal protection:** Reject filenames starting with `/` or containing `..` during unpack (Rule 2 - security)
+- **Error continuation:** HMAC failure skips the file; SHA-256 mismatch warns but still writes (per FORMAT.md Section 10 guidance)
+- **Flags byte logic:** Header flags bit 0 is set only when at least one file in the archive has compression_flag=1
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 2 (Core Archiver) is complete: all modules wired and functional
+- Ready for Phase 3 (Round-trip verification / integration tests)
+- Two dead-code warnings remain for `format::entry_size` and `format::compute_toc_size` helper functions (usable by future code)
+- All obfuscation features deferred to Phase 6 as per ROADMAP
+
+## Self-Check: PASSED
+
+All 2 modified files verified present. Task commit (be50707) verified in git log.
+
+---
+*Phase: 02-core-archiver*
+*Completed: 2026-02-24*