Added comprehensive documentation to make it crystal clear that:
- Timestamps are Unix epoch timestamps (seconds since 1970-01-01 00:00:00 UTC) stored as floats
- Hash input format is "{timestamp}:{content}" with float-to-string conversion
- Example: "1702345678.123456:Suspicious process detected"
- Full float precision is preserved, ensuring forensic tamper-evidence
Updated documentation in:
- trace/models/__init__.py: Added field comments and detailed docstring for calculate_hash()
- trace/crypto.py: Added comprehensive docstring for hash_content() with examples
- CLAUDE.md: Added detailed explanation in Integrity System section
Added CLI features for rapid observation logging during live forensic analysis:
Context Management:
- --show-context: Display active case and evidence
- --list: List all cases and evidence in hierarchy
- --switch-case: Change active case (by ID or case number)
- --switch-evidence: Change active evidence (by ID or name)
Case/Evidence Creation:
- --new-case: Create new case with optional --name and --investigator
- --new-evidence: Create new evidence with optional --description
Enhanced Note-Taking:
- --stdin: Read note content from stdin for piping command output
- --case: Add note to specific case without changing active context
- --evidence: Add note to specific evidence without changing active context
All context switching commands support both UUIDs and human-friendly identifiers
(case numbers for cases, names for evidence). Creating new items automatically
sets them as active. Override flags allow temporary context changes without
modifying the active state.
Updated CLAUDE.md with comprehensive CLI command examples organized by workflow.
Major refactoring to organize code into focused, single-responsibility modules
that are easier for AI coding agents and developers to navigate and modify.
**Module Reorganization:**
Models Package (trace/models/):
- Moved models.py content into models/__init__.py
- Extracted IOC extraction into models/extractors/ioc_extractor.py (236 lines)
- Extracted tag extraction into models/extractors/tag_extractor.py (34 lines)
- Reduced duplication and improved maintainability
Storage Package (trace/storage_impl/):
- Split storage.py (402 lines) into focused modules:
- storage.py: Main Storage class (112 lines)
- state_manager.py: StateManager for context/settings (92 lines)
- lock_manager.py: Cross-platform file locking (87 lines)
- demo_data.py: Demo case creation (143 lines)
- Added backward-compatible wrapper at trace/storage.py
TUI Utilities (trace/tui/):
- Created rendering package:
- colors.py: Color pair constants and initialization (43 lines)
- text_renderer.py: Text rendering with highlighting (137 lines)
- Created handlers package:
- export_handler.py: Export functionality (238 lines)
- Main tui.py (3307 lines) remains for future refactoring
**Benefits:**
- Smaller, focused files (most < 250 lines)
- Clear single responsibilities
- Easier to locate and modify specific functionality
- Better separation of concerns
- Reduced cognitive load for AI agents
- All tests pass, no features removed
**Testing:**
- All existing tests pass
- Imports verified
- CLI and storage functionality tested
- Backward compatibility maintained
Updated CLAUDE.md to document new architecture and AI optimization strategy.
