docs(07-01): complete format spec update plan

- SUMMARY.md with execution metrics and self-check - STATE.md updated: Phase 7 complete, progress 58% - ROADMAP.md: Phase 7 marked complete (1/1 plans) - REQUIREMENTS.md: FMT-09, FMT-10, FMT-11, FMT-12 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 21:28:15 +03:00
parent 37f7dd1f83
commit 034a6939f1
4 changed files with 136 additions and 21 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -63,10 +63,10 @@

 ### Format (Бинарный формат)

- [ ] **FMT-09**: Тип записи в TOC entry (файл/директория) — 1 байт
- [ ] **FMT-10**: Unix permission bits (mode) в TOC entry — 2 байта (u16)
- [ ] **FMT-11**: Относительные пути с `/` разделителем вместо filename-only
- [ ] **FMT-12**: Обновлённая спецификация FORMAT.md с новыми полями
+- [x] **FMT-09**: Тип записи в TOC entry (файл/директория) — 1 байт
+- [x] **FMT-10**: Unix permission bits (mode) в TOC entry — 2 байта (u16)
+- [x] **FMT-11**: Относительные пути с `/` разделителем вместо filename-only
+- [x] **FMT-12**: Обновлённая спецификация FORMAT.md с новыми полями

 ### Directory (Поддержка директорий)

@@ -161,10 +161,10 @@
 | TST-01 | Phase 3 | Complete |
 | TST-02 | Phase 3 | Complete |
 | TST-03 | Phase 3 | Complete |
-| FMT-09 | Phase 7 | Pending |
-| FMT-10 | Phase 7 | Pending |
-| FMT-11 | Phase 7 | Pending |
-| FMT-12 | Phase 7 | Pending |
+| FMT-09 | Phase 7 | Complete |
+| FMT-10 | Phase 7 | Complete |
+| FMT-11 | Phase 7 | Complete |
+| FMT-12 | Phase 7 | Complete |
 | DIR-01 | Phase 8 | Pending |
 | DIR-02 | Phase 8 | Pending |
 | DIR-03 | Phase 8 | Pending |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -144,7 +144,7 @@ Plans:
 **Plans**: 1 plan

 Plans:
- [ ] 07-01-PLAN.md -- Update TOC entry definition (entry_type, permissions, path semantics) and worked example with directory archive
+- [x] 07-01-PLAN.md -- Update TOC entry definition (entry_type, permissions, path semantics) and worked example with directory archive

 ### Phase 8: Rust Directory Archiver
 **Goal**: `pack` accepts directories and recursively archives them with full path hierarchy and permissions; `unpack` restores the complete directory tree
@@ -205,7 +205,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10
 | 4. Kotlin Decoder | v1.0 | 1/1 | Complete | 2026-02-25 |
 | 5. Shell Decoder | v1.0 | 2/2 | Complete | 2026-02-25 |
 | 6. Obfuscation Hardening | v1.0 | 2/2 | Complete | 2026-02-25 |
-| 7. Format Spec Update | v1.1 | 0/1 | Planned | - |
+| 7. Format Spec Update | v1.1 | 1/1 | Complete | 2026-02-26 |
 | 8. Rust Directory Archiver | v1.1 | 0/TBD | Not started | - |
 | 9. Kotlin Decoder Update | v1.1 | 0/TBD | Not started | - |
 | 10. Shell Decoder Update | v1.1 | 0/TBD | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -9,19 +9,23 @@ See: .planning/PROJECT.md (updated 2026-02-25)

 ## Current Position

-Phase: 7 of 11 (Format Spec Update) -- first phase of v1.1
-Plan: Not yet planned
-Status: Ready to plan
-Last activity: 2026-02-25 -- v1.1 roadmap created (phases 7-11)
+Phase: 7 of 11 (Format Spec Update) -- COMPLETE
+Plan: 1 of 1 -- COMPLETE
+Status: Phase 7 complete, ready for Phase 8
+Last activity: 2026-02-26 -- Phase 7 Plan 01 executed (FORMAT.md v1.1 update)

-Progress: [##########..........] 55% (10/~18 plans estimated)
+Progress: [###########.........] 58% (11/~19 plans estimated)

 ## Performance Metrics

-**Velocity (from v1.0):**
- Total plans completed: 10
- Average duration: 3.6 min
- Total execution time: 0.6 hours
+**Velocity:**
+- Total plans completed: 11
+- Average duration: 3.8 min
+- Total execution time: 0.7 hours
+
+| Phase | Plan | Duration | Tasks | Files |
+|-------|------|----------|-------|-------|
+| 07-01 | Format Spec Update | 8 min | 2 | 1 |

 ## Accumulated Context

@@ -37,6 +41,9 @@ Recent decisions affecting current work:
 - v1.0: Two-pass TOC serialization for correct data_offsets with encrypted TOC size
 - v1.1: No backward compatibility with v1.0 archives (format version bump)
 - v1.1: Only mode bits (no uid/gid, no timestamps, no symlinks)
+- v1.1: entry_type and permissions fields placed AFTER name, BEFORE original_size in TOC entry
+- v1.1: Directory entries use zero-filled crypto fields (uniform entry structure)
+- v1.1: Entry size formula: 104 + name_length (was 101)

 ### Pending Todos

@@ -48,6 +55,6 @@ None.

 ## Session Continuity

-Last session: 2026-02-25
-Stopped at: v1.1 roadmap created -- ready to plan Phase 7
+Last session: 2026-02-26
+Stopped at: Completed 07-01-PLAN.md -- Phase 7 complete, ready for Phase 8
 Resume file: None
--- a/.planning/phases/07-format-spec-update/07-01-SUMMARY.md
+++ b/.planning/phases/07-format-spec-update/07-01-SUMMARY.md
@@ -0,0 +1,108 @@
+---
+phase: 07-format-spec-update
+plan: 01
+subsystem: format
+tags: [binary-format, toc, entry-type, permissions, directory-support]
+
+# Dependency graph
+requires:
+  - phase: 01-format-specification
+    provides: "v1.0 FORMAT.md with header, TOC entry, data block definitions and worked example"
+provides:
+  - "v1.1 FORMAT.md with entry_type (u8), permissions (u16 LE), relative path semantics"
+  - "Updated worked example with 3-entry directory archive (2 dirs + 1 file, 427 bytes)"
+  - "Version bumped to 2 with compatibility rules"
+affects: [08-rust-directory-archiver, 09-kotlin-decoder-update, 10-shell-decoder-update, 11-directory-cross-validation]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Directory entries have all-zero crypto fields (iv, hmac, sha256, sizes)"
+    - "Parent-before-child ordering in TOC entries"
+    - "Entry size formula: 104 + name_length (was 101)"
+
+key-files:
+  created: []
+  modified:
+    - "docs/FORMAT.md"
+
+key-decisions:
+  - "entry_type and permissions fields placed AFTER name and BEFORE original_size in TOC entry"
+  - "Directory entries use zero-filled iv/hmac/sha256 (not omitted) to keep fixed-offset field structure"
+  - "v1.0 worked example fully replaced (not kept as subsection) since format version changed"
+
+patterns-established:
+  - "Directory entry pattern: entry_type=0x01, all sizes=0, all crypto=zeroed, no data block"
+  - "Permission bits: lower 12 bits of POSIX mode_t stored as u16 LE"
+  - "Entry names: relative paths with / separator, no leading /, no .., no trailing /"
+
+requirements-completed: [FMT-09, FMT-10, FMT-11, FMT-12]
+
+# Metrics
+duration: 8min
+completed: 2026-02-26
+---
+
+# Phase 7 Plan 01: Format Spec Update Summary
+
+**v1.1 FORMAT.md with entry_type (u8) and permissions (u16 LE) fields, relative path semantics, and 427-byte worked example showing nested directory archive**
+
+## Performance
+
+- **Duration:** 8 min
+- **Started:** 2026-02-26T18:17:57Z
+- **Completed:** 2026-02-26T18:26:07Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- FORMAT.md Section 5 extended with entry_type and permissions fields, Entry Type Values table, Permission Bits Layout table, and Entry Name Semantics subsection
+- Entry size formula updated from 101 to 104 + name_length across all references
+- Format version bumped from 1 to 2 with detailed v2 changes in Version Compatibility section
+- Complete v1.1 worked example: 3 entries (project/src dir, project/src/main.rs file, project/empty dir) with verified 427-byte layout
+- Decode Order of Operations updated for directory handling (check entry_type, mkdir -p, chmod, skip to next entry)
+- Shell decode walkthrough demonstrates both directory creation and file extraction flows
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Update TOC entry definition with entry_type, permissions, and path semantics** - `e7535da` (feat)
+2. **Task 2: Write updated worked example with directory archive** - `37f7dd1` (feat)
+
+## Files Created/Modified
+- `docs/FORMAT.md` - Complete v1.1 binary format specification with directory support fields and new worked example
+
+## Decisions Made
+- entry_type and permissions fields placed AFTER name and BEFORE original_size -- maintains variable-length name at the start (name_length prefix still works), new fields are fixed-size and easy to read after name
+- Directory entries use zero-filled crypto fields rather than omitting them -- keeps the entry structure uniform and allows sequential parsing with the same field offsets
+- v1.0 worked example fully replaced rather than kept as a subsection -- the old example uses version=1 and the old entry layout, keeping it would cause confusion
+- Renamed header field from file_count to entry_count -- reflects that directories are now counted
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- FORMAT.md is the normative reference for all three decoders (Rust, Kotlin, Shell)
+- Phase 8 (Rust Directory Archiver) can implement against the new entry_type, permissions, and relative path fields
+- Phases 9 and 10 (Kotlin and Shell decoder updates) have unambiguous field tables and a worked example to test against
+- The 427-byte worked example with verified offsets serves as a golden reference for implementation testing
+
+## Self-Check: PASSED
+
+- FOUND: docs/FORMAT.md
+- FOUND: .planning/phases/07-format-spec-update/07-01-SUMMARY.md
+- FOUND: e7535da (Task 1 commit)
+- FOUND: 37f7dd1 (Task 2 commit)
+
+---
+*Phase: 07-format-spec-update*
+*Completed: 2026-02-26*