docs(02-02): complete archive commands plan

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

.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*