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