docs(05-01): complete shell decoder plan

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

.planning/REQUIREMENTS.md

@@ -49,9 +49,9 @@
 
 ### Shell Decoder (Shell декодер)
 
-- [ ] **SHL-01**: Shell-скрипт деархивации через busybox (dd, xxd, openssl, gunzip)
+- [x] **SHL-01**: Shell-скрипт деархивации через busybox (dd, xxd, openssl, gunzip)
-- [ ] **SHL-02**: openssl enc -aes-256-cbc с -K/-iv/-nosalt для raw key mode
+- [x] **SHL-02**: openssl enc -aes-256-cbc с -K/-iv/-nosalt для raw key mode
-- [ ] **SHL-03**: Поддержка файлов с не-ASCII именами (кириллица)
+- [x] **SHL-03**: Поддержка файлов с не-ASCII именами (кириллица)
 
 ### Testing (Тестирование)
 
@@ -117,9 +117,9 @@
 | KOT-02 | Phase 4 | Complete |
 | KOT-03 | Phase 4 | Complete |
 | KOT-04 | Phase 4 | Complete |
-| SHL-01 | Phase 5 | Pending |
+| SHL-01 | Phase 5 | Complete |
-| SHL-02 | Phase 5 | Pending |
+| SHL-02 | Phase 5 | Complete |
-| SHL-03 | Phase 5 | Pending |
+| SHL-03 | Phase 5 | Complete |
 | TST-01 | Phase 3 | Complete |
 | TST-02 | Phase 3 | Complete |
 | TST-03 | Phase 3 | Complete |

.planning/STATE.md

@@ -5,22 +5,22 @@
 See: .planning/PROJECT.md (updated 2026-02-24)
 
 **Core value:** Archive impossible to unpack without knowing the format -- standard tools (7z, tar, unzip, binwalk) cannot recognize or extract contents
-**Current focus:** Phase 4 complete, ready for Phase 5
+**Current focus:** Phase 5 in progress (Shell Decoder)
 
 ## Current Position
 
-Phase: 4 of 6 (Kotlin Decoder) -- COMPLETE
+Phase: 5 of 6 (Shell Decoder)
-Plan: 1 of 1 in current phase (all done)
+Plan: 1 of 2 in current phase
-Status: Phase 4 complete, ready for Phase 5
+Status: Plan 1 complete, Plan 2 (cross-validation tests) remaining
-Last activity: 2026-02-25 -- Kotlin archive decoder with full decode pipeline and cross-validation test script
+Last activity: 2026-02-25 -- Busybox-compatible shell decoder script (shell/decode.sh)
 
-Progress: [██████░░░░] 60%
+Progress: [███████░░░] 70%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 6
+- Total plans completed: 7
-- Average duration: 4.5 min
+- Average duration: 4.1 min
 - Total execution time: 0.5 hours
 
 **By Phase:**
@@ -31,9 +31,10 @@ Progress: [██████░░░░] 60%
 | 2. Core Archiver | 2/2 | 6 min | 3 min |
 | 3. Round-Trip Verification | 2/2 | 8 min | 4 min |
 | 4. Kotlin Decoder | 1/1 | 4 min | 4 min |
+| 5. Shell Decoder | 1/2 | 3 min | 3 min |
 
 **Recent Trend:**
-- Last 5 plans: 4min, 2min, 3min, 5min, 4min
+- Last 5 plans: 2min, 3min, 5min, 4min, 3min
 - Trend: stable
 
 *Updated after each plan completion*
@@ -66,6 +67,11 @@ Recent decisions affecting current work:
 - Phase 4: RandomAccessFile for seeking to data blocks instead of reading entire archive into memory
 - Phase 4: HMAC failure skips file, SHA-256 mismatch warns but writes (matching Rust behavior)
 - Phase 4: Kotlin signed byte handling with .toByte() for literals > 0x7F, contentEquals() for ByteArray comparison
+- Phase 5: POSIX sh (not bash) for maximum busybox compatibility
+- Phase 5: xxd/od auto-detection at startup for hex conversion
+- Phase 5: Graceful HMAC degradation when openssl lacks -mac support
+- Phase 5: Extract ciphertext to temp file before decryption (avoids pipe buffering issues)
+- Phase 5: LC_ALL=C for predictable byte handling across locales
 
 ### Pending Todos
 
@@ -73,12 +79,12 @@ None yet.
 
 ### Blockers/Concerns
 
-- Open question: Does target busybox have `openssl enc -aes-256-cbc` with `-K`/`-iv` flags? (affects Phase 5)
+- RESOLVED: openssl enc with -K/-iv flags implemented in shell decoder; script fails gracefully if openssl missing
-- Open question: Is `xxd` available in target busybox? Fallback: `od` (affects Phase 5; spec includes od fallback functions)
+- RESOLVED: xxd/od auto-detection implemented in shell decoder (xxd primary, od fallback)
 - RESOLVED: HMAC uses same key as AES in v1 (decided in Phase 1 spec, v2 will use HKDF)
 
 ## Session Continuity
 
 Last session: 2026-02-25
-Stopped at: Completed 04-01-PLAN.md (Kotlin decoder + cross-validation tests; Phase 4 complete)
+Stopped at: Completed 05-01-PLAN.md (Shell decoder script; Phase 5 Plan 1 of 2)
 Resume file: None

.planning/phases/05-shell-decoder/05-01-SUMMARY.md

@@ -0,0 +1,98 @@
+---
+phase: 05-shell-decoder
+plan: 01
+subsystem: shell-decoder
+tags: [posix-sh, busybox, openssl, aes-256-cbc, dd, xxd, od, hmac, sha256]
+
+# Dependency graph
+requires:
+  - phase: 01-format-specification
+    provides: "FORMAT.md binary format spec with shell decoder reference (Section 13)"
+  - phase: 02-core-archiver
+    provides: "Rust archiver for creating test archives"
+provides:
+  - "shell/decode.sh -- busybox-compatible POSIX shell decoder script"
+  - "Full decode pipeline: header -> TOC -> HMAC verify -> decrypt -> decompress -> SHA-256 verify -> write"
+affects: [06-obfuscation]
+
+# Tech tracking
+tech-stack:
+  added: [sh, dd, openssl-enc, xxd, od, gunzip, sha256sum]
+  patterns: [posix-shell-binary-parsing, xxd-od-fallback, hmac-graceful-degradation]
+
+key-files:
+  created:
+    - shell/decode.sh
+
+key-decisions:
+  - "POSIX sh (not bash) for maximum busybox compatibility"
+  - "xxd/od auto-detection at startup for hex conversion"
+  - "Graceful HMAC degradation when openssl lacks -mac support"
+  - "Extract ciphertext to temp file before decryption (avoids pipe issues)"
+  - "LC_ALL=C for predictable byte handling"
+
+patterns-established:
+  - "dd-based binary parsing with hex byte-swap for little-endian integers"
+  - "Temp file cleanup via trap on EXIT"
+  - "HMAC computed from raw archive bytes (IV from TOC offset + ciphertext), not from hex variables"
+
+requirements-completed: [SHL-01, SHL-02, SHL-03]
+
+# Metrics
+duration: 3min
+completed: 2026-02-25
+---
+
+# Phase 5 Plan 1: Shell Decoder Summary
+
+**Busybox-compatible POSIX shell decoder with full decode pipeline (dd+xxd/od for parsing, openssl enc for AES-256-CBC decryption, HMAC verification with graceful degradation, SHA-256 integrity checks)**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-02-24T22:37:48Z
+- **Completed:** 2026-02-24T22:40:29Z
+- **Tasks:** 1
+- **Files created:** 1
+
+## Accomplishments
+- Created self-contained POSIX shell decoder script (250 lines) implementing full FORMAT.md Section 10 decode pipeline
+- Verified byte-identical extraction against Rust archiver output (ASCII and Cyrillic filenames)
+- Implemented xxd/od auto-detection fallback for hex conversion on minimal busybox systems
+- HMAC graceful degradation: detects openssl HMAC support at startup, skips with warning if unavailable
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create shell/decode.sh with full decode pipeline** - `6df2639` (feat)
+
+## Files Created/Modified
+- `shell/decode.sh` - Busybox-compatible POSIX shell script implementing complete archive decode pipeline
+
+## Decisions Made
+- Used POSIX sh (not bash) with no bash-specific syntax for maximum compatibility
+- Auto-detect xxd vs od at startup; define read_hex using whichever is available
+- Graceful HMAC degradation: test openssl HMAC capability at startup, set SKIP_HMAC flag
+- Extract ciphertext to temp file before decryption (avoids pipe buffering issues with openssl enc)
+- Set LC_ALL=C at script top for predictable byte handling across locales
+- Used printf-based substring extraction instead of bash ${var:offset:len} for POSIX compliance
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Shell decoder complete, ready for cross-validation testing in Plan 2
+- Script verified against Rust archiver with both ASCII and Cyrillic filenames
+- Phase 6 (obfuscation) can extend the script with XOR header deobfuscation and TOC decryption
+
+---
+*Phase: 05-shell-decoder*
+*Completed: 2026-02-25*