docs(05-01): complete shell decoder plan

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

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