cc-context-stats 1.7.0 → 1.8.1

package/CHANGELOG.md

@@ -1,163 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [1.7.0] - 2026-03-14
-
-### Added
-
-- **Configurable colors** - Custom color themes via `~/.claude/statusline.conf` using named colors (`bright_cyan`) or hex codes (`#7dcfff`). Six configurable slots: `color_green`, `color_yellow`, `color_red`, `color_blue`, `color_magenta`, `color_cyan`
-- **`context-stats explain` command** - Diagnostic dump that pretty-prints Claude Code's JSON context with derived values (free tokens, autocompact buffer, effective free), active config, vim/agent/output_style extensions, and raw JSON. Supports `--no-color` flag
-- **24-bit true color support** - Hex color codes (`#rrggbb`) are converted to ANSI 24-bit escape sequences for full RGB color customization
-- **Cross-implementation sync documentation** - Added sync points table to CLAUDE.md documenting triplicated logic across Python, Node.js, and Bash implementations
-
-### Changed
-
-- **ColorManager accepts overrides** - `ColorManager` now takes an optional `overrides` dict, allowing config-driven color customization throughout the package
-- **Git info uses configurable colors** - Branch and change count colors now respect user color overrides in all three implementations
-- **Config parsing preserves raw values** - Config reader now preserves case for color values while lowercasing only for boolean comparison
-
-## [1.6.2] - 2026-03-13
-
-### Fixed
-
-- **Delta calculation parity** - Python statusline now reads correct CSV indices (3+5+6) for context usage delta, matching Node.js behavior
-- **Missing duplicate-entry guard** - Python statusline now skips state file writes when token count is unchanged, preventing file bloat
-- **Missing state file rotation** - Python statusline now calls rotation after writes (10k/5k threshold), matching Node.js
-- **Missing git timeout** - Added 5-second timeout to git subprocess calls in standalone Python statusline script
-- **Broad exception handling** - Narrowed `except Exception` to `(OSError, ValueError)` for state reads and `OSError` for writes
-- **Stale CSV format comments** - Added missing `context_window_size` field to header comments in both Python and Node.js scripts
-
-### Added
-
-- **Delta parity tests** - 4 new bats tests verifying Python/Node.js produce identical deltas, handle first-run/decrease/dedup correctly
-
-## [1.6.1] - 2026-03-13
-
-### Fixed
-
-- **Footer version drift** - Corrected stale version `1.2.3` in bash script and `1.0.0` default in Python renderer to match actual release version
-- **Footer project name** - Renamed `claude-statusline` to `cc-context-stats` in the footer display across bash and Python implementations
-- **Install version embedding** - Install scripts now read version from `package.json` and embed it into the installed script, preventing future version drift
-
-## [1.6.0] - 2026-03-13
-
-### Added
-
-- **CLI `--version` flag** - `context-stats --version` / `-V` now prints the current version
-- **State file rotation** - Automatic rotation at 10,000 lines (keeps most recent 5,000) to prevent unbounded file growth
-- **Session ID validation** - Rejects path-traversal characters (`/`, `\`, `..`, null bytes) for security
-- **Git command timeout** - 5-second timeout on git operations in both Python and Node.js implementations
-- **Core data pipeline unit tests** - 51 tests across 6 classes covering config, state, formatters, graph, and CLI
-- **Cross-implementation parity test** - Ensures Python and Node.js statusline scripts produce consistent output
-- **Stderr warnings** - Critical error paths now emit warnings to stderr for debugging
-- **CSV format documentation** - Formal specification of the 14-field state file format
-- **Comma guard for workspace paths** - Commas in `workspace_project_dir` are replaced with underscores before CSV write
-- **Open-source standard files** - Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GitHub issue/PR templates
-- **NPM Package** - `cc-context-stats` now available on npm for JavaScript/Node.js environments
-
-### Changed
-
-- **Package Metadata** - Synchronized package descriptions across npm and PyPI for consistency
-- **Installation Section** - Moved shell script installation to the top of README as the recommended method
-
-### Dependencies
-
-- Bumped prettier from 3.7.4 to 3.8.0
-
-## [1.2.0] - 2025-01-08
-
-### Added
-
-- **Context Zones** - Status indicator based on context usage:
-  - 🟢 Smart Zone (< 40%): "You are in the smart zone"
-  - 🟡 Dumb Zone (40-80%): "You are in the dumb zone - Dex Horthy says so"
-  - 🔴 Wrap Up Zone (> 80%): "Better to wrap up and start a new session"
-- **Project name display** - Header now shows "Context Stats (project-name • session-id)"
-
-### Changed
-
-- **Watch mode enabled by default** - `context-stats` now runs in live monitoring mode (2s refresh)
-- **Delta graph by default** - Shows "Context Growth Per Interaction" instead of both graphs
-- Added `--no-watch` flag to show graphs once and exit
-- Simplified installer - no script selection, auto-overwrite existing files
-- Renamed graph labels to focus on context (e.g., "Context Usage Over Time")
-- Cleaned up session summary - removed clutter, highlighted status
-
-## [1.1.0] - 2025-01-08
-
-### Changed
-
-- **BREAKING**: Renamed package from `cc-statusline` to `cc-context-stats`
-- **BREAKING**: Renamed `token-graph` CLI command to `context-stats`
-- Pivoted project focus to real-time token monitoring and context tracking
-- Updated tagline: "Never run out of context unexpectedly"
-
-### Migration
-
-If upgrading from `cc-statusline`:
-
-```bash
-pip uninstall cc-statusline
-pip install cc-context-stats
-```
-
-The `claude-statusline` command still works. Replace `token-graph` with `context-stats`.
-
-## [1.0.2] - 2025-01-08
-
-### Fixed
-
-- Fixed remaining context showing negative values in context-stats by using `current_used_tokens` instead of cumulative `total_input_tokens + total_output_tokens`
-- Fixed ANSI escape codes not rendering properly in watch mode by using `sys.stdout.write()` instead of `print()` for cursor control sequences
-- Fixed color codes in summary statistics using ColorManager instead of raw ANSI constants
-
-## [1.0.1] - 2025-01-07
-
-### Added
-
-- pip/uv installable Python package (`cc-statusline` on PyPI)
-- `context_window_size` field to state file for tracking remaining context
-- Remaining context display in context-stats summary
-
-### Fixed
-
-- Restored executable permissions on script files
-- Fixed stdin detection in pipe mode using INTERACTIVE flag
-
-### Changed
-
-- Cleaned up unused `show_io_tokens` option
-- Fixed shellcheck warnings in shell scripts
-
-## [1.0.0] - 2025-01-06
-
-### Added
-
-- Comprehensive test suite with Bats (Bash), pytest (Python), and Jest (Node.js)
-- GitHub Actions CI/CD pipeline with multi-platform testing
-- Code quality tools: ShellCheck, Ruff, ESLint, Prettier
-- Pre-commit hooks for automated code quality checks
-- EditorConfig for consistent formatting across editors
-- CONTRIBUTING.md with development setup instructions
-- Dependabot configuration for automated dependency updates
-- Release automation workflow
-- Full-featured status line script (`statusline-full.sh`)
-- Git-aware status line script (`statusline-git.sh`)
-- Minimal status line script (`statusline-minimal.sh`)
-- Cross-platform Python implementation (`statusline.py`)
-- Cross-platform Node.js implementation (`statusline.js`)
-- Interactive installer script (`install.sh`)
-- Configuration examples for Claude Code
-- Autocompact (AC) buffer indicator
-- Context window usage with color-coded percentages
-- Git branch and uncommitted changes display
-
-## [0.x] - Pre-release
-
-Initial development versions with basic status line functionality.

package/CLAUDE.md

@@ -1,66 +0,0 @@
-# CLAUDE.md
-
-## Project Purpose
-
-cc-context-stats provides real-time context window monitoring for Claude Code sessions. It tracks token consumption over time and displays live ASCII graphs so users can see how much context remains.
-
-## Dual-Implementation Rationale
-
-The statusline is implemented in three languages (Bash, Python, Node.js) so users can choose whichever runtime they have available. Claude Code invokes the statusline script via stdin JSON pipe — any implementation that reads JSON from stdin and writes formatted text to stdout works. The Python and Node.js implementations also persist state to CSV files read by the `context-stats` CLI.
-
-## CSV Format Contract
-
-State files are append-only CSV at `~/.claude/statusline/statusline.<session_id>.state` with 14 comma-separated fields. See [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) for the full field specification. Key constraint: `workspace_project_dir` has commas replaced with underscores before writing.
-
-## Statusline Script Landscape
-
-| Script | Language | State writes | Notes |
-|---|---|---|---|
-| `scripts/statusline-full.sh` | Bash | No | Full display, requires `jq` |
-| `scripts/statusline-git.sh` | Bash | No | Git-focused variant |
-| `scripts/statusline-minimal.sh` | Bash | No | Minimal variant |
-| `scripts/statusline.py` | Python 3 | Yes | Pip-installable via package |
-| `scripts/statusline.js` | Node.js | Yes | Standalone script |
-
-## Test Commands
-
-```bash
-# Python tests
-source venv/bin/activate
-pytest tests/python/ -v
-
-# Node.js tests
-npm test
-
-# Bash integration tests
-bats tests/bash/*.bats
-
-# All tests
-pytest && npm test && bats tests/bash/*.bats
-```
-
-## Key Architectural Decisions
-
-- **Append-only CSV state files** with rotation at 10,000 lines (keeps most recent 5,000)
-- **No network requests** — all data stays local in `~/.claude/statusline/`
-- **Session ID validation** — rejects `/`, `\`, `..`, and null bytes for path-traversal defense
-- **5-second git command timeout** in both Python and Node.js implementations
-- **Config via `~/.claude/statusline.conf`** — simple key=value pairs
-
-## Cross-Implementation Sync Points
-
-The following logic is duplicated across three implementations and **must be kept in sync** when modified:
-
-| Logic | Package (`src/`) | Standalone Python (`scripts/statusline.py`) | Node.js (`scripts/statusline.js`) |
-|---|---|---|---|
-| Config parsing | `core/config.py` | `read_config()` | `readConfig()` |
-| Color name map | `core/colors.py:COLOR_NAMES` | `_COLOR_NAMES` | `COLOR_NAMES` |
-| Color parser | `core/colors.py:parse_color()` | `_parse_color()` | `parseColor()` |
-| Git info | `core/git.py:get_git_info()` | `get_git_info()` | `getGitInfo()` |
-| State rotation | `core/state.py` | `maybe_rotate_state_file()` | `maybeRotateStateFile()` |
-
-## Cross-References
-
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture and data flow
-- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) — setup, testing, and contribution guide
-- [docs/CSV_FORMAT.md](docs/CSV_FORMAT.md) — state file field specification

package/CODE_OF_CONDUCT.md

@@ -1,59 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-We as members, contributors, and leaders pledge to make participation in our
-community a harassment-free experience for everyone, regardless of age, body
-size, visible or invisible disability, ethnicity, sex characteristics, gender
-identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, religion, or sexual identity
-and orientation.
-
-We pledge to act and interact in ways that contribute to an open, welcoming,
-diverse, inclusive, and healthy community.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment:
-
-* Demonstrating empathy and kindness toward other people
-* Being respectful of differing opinions, viewpoints, and experiences
-* Giving and gracefully accepting constructive feedback
-* Accepting responsibility and apologizing to those affected by our mistakes
-* Focusing on what is best for the overall community
-
-Examples of unacceptable behavior:
-
-* The use of sexualized language or imagery, and sexual attention or advances
-* Trolling, insulting or derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information without explicit permission
-* Other conduct which could reasonably be considered inappropriate
-
-## Enforcement Responsibilities
-
-Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
-or harmful.
-
-## Scope
-
-This Code of Conduct applies within all community spaces, and also applies when
-an individual is officially representing the community in public spaces.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at
-luongnv89@gmail.com.
-
-All complaints will be reviewed and investigated promptly and fairly.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
-
-[homepage]: https://www.contributor-covenant.org

package/CONTRIBUTING.md

@@ -1,240 +0,0 @@
-# Contributing to Claude Code Status Line
-
-Thank you for your interest in contributing to Claude Code Status Line! This document provides guidelines and instructions for contributing.
-
-## Development Setup
-
-### Prerequisites
-
-- **Git** - Version control
-- **jq** - JSON processor (for bash scripts)
-- **Python 3.9+** - For Python script and testing
-- **Node.js 18+** - For Node.js script and testing
-- **Bats** - Bash Automated Testing System
-
-### Installing Dependencies
-
-#### macOS
-
-```bash
-# Install system dependencies
-brew install jq bats-core
-
-# Clone the repository
-git clone https://github.com/luongnv89/cc-context-stats.git
-cd claude-statusline
-
-# Install Python dependencies
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements-dev.txt
-
-# Install Node.js dependencies
-npm install
-
-# Install pre-commit hooks
-pre-commit install
-```
-
-#### Linux (Ubuntu/Debian)
-
-```bash
-# Install system dependencies
-sudo apt-get update
-sudo apt-get install -y jq bats
-
-# Clone the repository
-git clone https://github.com/luongnv89/cc-context-stats.git
-cd claude-statusline
-
-# Install Python dependencies
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements-dev.txt
-
-# Install Node.js dependencies
-npm install
-
-# Install pre-commit hooks
-pre-commit install
-```
-
-## Project Structure
-
-```text
-claude-statusline/
-├── scripts/                    # Main scripts
-│   ├── statusline-full.sh      # Full-featured bash script
-│   ├── statusline-git.sh       # Git-aware bash script
-│   ├── statusline-minimal.sh   # Minimal bash script
-│   ├── statusline.py           # Python cross-platform script
-│   └── statusline.js           # Node.js cross-platform script
-├── config/                     # Configuration examples
-├── tests/                      # Test suites
-│   ├── fixtures/json/          # Test fixtures
-│   ├── bash/                   # Bats tests
-│   ├── python/                 # Pytest tests
-│   └── node/                   # Jest tests
-├── .github/workflows/          # CI/CD workflows
-├── install.sh                  # Installation script
-└── README.md                   # Documentation
-```
-
-## Running Tests
-
-### All Tests
-
-```bash
-# Run all tests
-npm test && pytest && bats tests/bash/*.bats
-```
-
-### Individual Test Suites
-
-```bash
-# Bash tests (requires bats)
-bats tests/bash/*.bats
-
-# Python tests
-pytest tests/python/ -v
-
-# Python tests with coverage
-pytest tests/python/ -v --cov=scripts --cov-report=html
-
-# Node.js tests
-npm test
-
-# Node.js tests with coverage
-npm run test:coverage
-```
-
-## Code Quality
-
-### Linting
-
-```bash
-# Run all linters
-pre-commit run --all-files
-
-# Individual linters
-ruff check scripts/statusline.py          # Python
-npx eslint scripts/statusline.js          # JavaScript
-shellcheck scripts/*.sh install.sh        # Bash
-```
-
-### Formatting
-
-```bash
-# Auto-format Python
-ruff format scripts/statusline.py
-
-# Auto-format JavaScript
-npx prettier --write scripts/statusline.js
-
-# Check formatting without modifying
-ruff format --check scripts/statusline.py
-npx prettier --check scripts/statusline.js
-```
-
-## Making Changes
-
-### 1. Create a Branch
-
-```bash
-git checkout -b feature/your-feature-name
-# or
-git checkout -b fix/your-bug-fix
-```
-
-### 2. Make Changes
-
-- Follow the existing code style
-- Add tests for new functionality
-- Update documentation if needed
-- Ensure all scripts produce consistent output
-
-### 3. Test Your Changes
-
-```bash
-# Run pre-commit hooks
-pre-commit run --all-files
-
-# Run all tests
-bats tests/bash/*.bats
-pytest tests/python/ -v
-npm test
-
-# Test scripts manually
-echo '{"model":{"display_name":"Test"}}' | ./scripts/statusline-full.sh
-echo '{"model":{"display_name":"Test"}}' | python3 ./scripts/statusline.py
-echo '{"model":{"display_name":"Test"}}' | node ./scripts/statusline.js
-```
-
-### 4. Commit Your Changes
-
-Use conventional commit messages:
-
-```bash
-git commit -m "feat: add new feature description"
-git commit -m "fix: fix bug description"
-git commit -m "docs: update documentation"
-git commit -m "test: add tests for feature"
-git commit -m "refactor: refactor code description"
-```
-
-### 5. Push and Create PR
-
-```bash
-git push origin feature/your-feature-name
-```
-
-Then create a Pull Request on GitHub.
-
-## Script Guidelines
-
-### Cross-Script Consistency
-
-All three implementations (bash, Python, Node.js) should produce identical output for the same input. When making changes:
-
-1. Update all three scripts consistently
-2. Run integration tests to verify parity
-3. Test on multiple platforms if possible
-
-### Output Format
-
-The status line output should follow this format:
-
-```text
-[Model] directory | branch [changes] | XXk free (XX%) [AC:XXk]
-```
-
-Components:
-
-- `[Model]` - AI model name (dim)
-- `directory` - Current directory name (blue)
-- `branch` - Git branch name (magenta)
-- `[changes]` - Uncommitted changes count (cyan)
-- `XXk free (XX%)` - Available context tokens (green/yellow/red)
-- `[AC:XXk]` - Autocompact buffer (dim)
-
-### Color Codes
-
-Use ANSI color codes consistently:
-
-- Blue: `\033[0;34m`
-- Magenta: `\033[0;35m`
-- Cyan: `\033[0;36m`
-- Green: `\033[0;32m`
-- Yellow: `\033[0;33m`
-- Red: `\033[0;31m`
-- Dim: `\033[2m`
-- Reset: `\033[0m`
-
-## Questions?
-
-If you have questions, feel free to:
-
-- Open an issue on GitHub
-- Check existing issues for similar questions
-
-Thank you for contributing!

package/RELEASE_NOTES.md

@@ -1,19 +0,0 @@
-## v1.6.0 — 2026-03-13
-
-### Features
-- **CLI `--version` flag** — `context-stats --version` / `-V` now prints the current version
-- **State file rotation** — Automatic rotation at 10,000 lines (keeps most recent 5,000) to prevent unbounded file growth
-- **Session ID validation** — Rejects path-traversal characters (`/`, `\`, `..`, null bytes) for security
-- **Git command timeout** — 5-second timeout on git operations in both Python and Node.js implementations
-- **Core data pipeline unit tests** — 51 tests across 6 classes covering config, state, formatters, graph, and CLI
-- **Cross-implementation parity test** — Ensures Python and Node.js statusline scripts produce consistent output
-- **Stderr warnings** — Critical error paths now emit warnings to stderr for debugging
-- **CSV format documentation** — Formal specification of the 14-field state file format
-- **Comma guard for workspace paths** — Commas in `workspace_project_dir` are replaced with underscores before CSV write
-- **Open-source standard files** — Added CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md, and GitHub issue/PR templates
-- **NPM Package** — `cc-context-stats` now available on npm for JavaScript/Node.js environments
-
-### Dependencies
-- Bumped prettier from 3.7.4 to 3.8.0
-
-**Full Changelog**: https://github.com/luongnv89/cc-context-stats/compare/v1.5.1...v1.6.0

package/SECURITY.md

@@ -1,44 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 1.5.x   | :white_check_mark: |
-| < 1.5   | :x:                |
-
-## Reporting a Vulnerability
-
-We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
-
-### How to Report
-
-1. **Do NOT** open a public GitHub issue for security vulnerabilities
-2. Email your findings to luongnv89@gmail.com
-3. Include detailed steps to reproduce the vulnerability
-4. Allow up to 48 hours for an initial response
-
-### What to Include
-
-- Type of vulnerability
-- Full paths of affected source files
-- Location of the affected source code (tag/branch/commit or direct URL)
-- Step-by-step instructions to reproduce
-- Proof-of-concept or exploit code (if possible)
-- Impact of the issue
-
-### What to Expect
-
-- Acknowledgment of your report within 48 hours
-- Regular updates on our progress
-- Credit in the security advisory (if desired)
-- Notification when the issue is fixed
-
-## Security Best Practices
-
-When contributing to this project:
-
-- Never commit secrets, API keys, or credentials
-- Use environment variables for sensitive configuration
-- Follow secure coding practices
-- Report any security concerns immediately

package/TODOS.md

@@ -1,72 +0,0 @@
-# TODOs
-
-Items identified from the HOLD SCOPE mega review (2026-03-12).
-
-## P1 — High Priority
-
-### ~~1. Cross-implementation parity test~~ ✅ Done
-**What:** Add a CI integration test that feeds identical JSON to both Python (`statusline.py`) and Node.js (`statusline.js`) scripts and asserts they write identical CSV state lines and produce equivalent stdout.
-**Why:** The two implementations share no code or schema contract. Drift has occurred before and will occur again. This catches it automatically.
-**Effort:** S
-**Depends on:** None
-**Status:** Implemented in `tests/bash/test_parity.bats` with CI job in `.github/workflows/ci.yml`. Archived as `openspec/changes/archive/2026-03-12-cross-impl-parity-test/`.
-
-### ~~2. Document CSV state file format + comma guard~~ ✅ Done
-**What:** Create `docs/CSV_FORMAT.md` documenting all 14 fields with types and examples. Fix `docs/ARCHITECTURE.md` which incorrectly states "each line is a JSON record." Sanitize `workspace_project_dir` to strip/escape commas before CSV serialization (in both Python and Node.js).
-**Why:** The CSV format is an implicit contract across 5 writer implementations with zero documentation. Commas in directory paths silently corrupt rows.
-**Effort:** S
-**Depends on:** None
-**Status:** Created `docs/CSV_FORMAT.md`, fixed ARCHITECTURE.md JSON→CSV, added comma→underscore guard in Python (`state.py`, `statusline.py`), Node.js (`statusline.js`), and bash (`statusline-full.sh`). Parity test with comma fixture passes. Archived as `openspec/changes/archive/2026-03-12-csv-format-doc-comma-guard/`.
-
-### ~~3. Stderr logging for critical error paths~~ ✅ Done
-**What:** Replace `except OSError: pass` with `sys.stderr.write()` warnings in: `StateFile.append_entry()`, `Config._create_default()`, `Config._read_config()`. Add `UnicodeDecodeError` to config read exception handling. Apply equivalent changes in `statusline.js`.
-**Why:** State write failures cause silent data loss — users see stale dashboards with no indication of why. Statusline output goes to stdout (consumed by Claude Code), so stderr is safe for diagnostics.
-**Effort:** S
-**Depends on:** None
-**Status:** Added `[statusline] warning:` stderr messages to all critical data pipeline error handlers in `config.py`, `state.py`, `statusline.py`, and `statusline.js`. Added `UnicodeDecodeError` to config read exception handling in both Python files. Non-critical handlers (git info, file migration) left silent.
-
-### ~~4. Core data pipeline unit tests~~ ✅ Done
-**What:** Add test files covering: (1) `StateEntry.from_csv_line` ↔ `to_csv_line` round-trip, (2) `calculate_deltas` and `detect_spike`, (3) zone threshold logic in `render_summary`. Cover edge cases: empty data, single entry, negative deltas, boundary percentages (39%/40%/79%/80%).
-**Why:** The primary user-facing feature (`context-stats` CLI) has zero unit tests on its core logic — CSV parsing, statistics, and zone detection are all untested.
-**Effort:** M
-**Depends on:** None
-**Status:** Implemented in `tests/python/test_data_pipeline.py` with 51 tests across 6 classes: TestStateEntryRoundTrip (14), TestStateEntryProperties (3), TestCalculateDeltas (8), TestCalculateStats (6), TestDetectSpike (10), TestZoneThresholds (10). Covers CSV round-trip with old/new formats, comma sanitization, boundary spike detection (exact 15%/3x thresholds), and zone boundaries at 39/40% and 79/80%.
-
-## P2 — Medium Priority
-
-### ~~5. State file cap + rotate~~ ✅ Done
-**What:** After `StateFile.append_entry()`, check line count. If >10,000 lines, truncate to the most recent 5,000. Apply in both Python and Node.js writers.
-**Why:** State files are append-only with no rotation. `read_history()` loads entire files into memory. Heavy users could accumulate 50k+ lines across long sessions.
-**Effort:** S
-**Depends on:** None
-**Status:** Added `_maybe_rotate()` to Python `StateFile` and `maybeRotateStateFile()` to Node.js `statusline.js`. Both use atomic temp-file + rename. Threshold: 10,000 lines, retain: 5,000 lines. Unit tests in `tests/python/test_state_rotation_validation.py` and `tests/node/rotation.test.js`.
-
-### ~~6. Sanitize session_id input~~ ✅ Done
-**What:** Reject session IDs containing `/`, `\`, or `..` at the CLI entry point (`parse_args`) and in `StateFile.__init__()`. Print a clear error message and exit.
-**Why:** Defense-in-depth against path traversal via `context-stats ../../etc/passwd`. Claude Code generates safe UUIDs, but the CLI accepts arbitrary user input.
-**Effort:** XS
-**Depends on:** None
-**Status:** Added `_validate_session_id()` helper in `state.py`, called in `StateFile.__init__()` and `parse_args()` in `context_stats.py`. Rejects `/`, `\`, `..`, and null bytes. Unit tests and CLI subprocess tests in `tests/python/test_state_rotation_validation.py`.
-
-### ~~7. Node.js git command timeout~~ ✅ Done
-**What:** Add `timeout: 5000` to both `execSync` calls in `statusline.js` `getGitInfo()`.
-**Why:** Python's `get_git_info()` has `timeout=5`. Node.js has none — git hangs (network FS, large repo) would block the statusline process indefinitely.
-**Effort:** XS
-**Depends on:** None
-**Status:** Added `timeout: 5000` to both `execSync` calls (`git rev-parse` and `git status`) in `getGitInfo()` in `scripts/statusline.js`.
-
-### ~~8. Repo-level CLAUDE.md~~ ✅ Done
-**What:** Create `CLAUDE.md` at repo root documenting: project purpose, dual-implementation rationale, CSV format contract, test running instructions (`pytest`, `npm test`, `bats`), key architectural decisions, and the 5-script statusline landscape.
-**Why:** Helps AI assistants and new contributors understand the project quickly. Currently the only CLAUDE.md is the user's personal global one.
-**Effort:** S
-**Depends on:** TODO 2 (CSV format doc) for cross-reference
-**Status:** Created `CLAUDE.md` at repo root with all required sections. Cross-references `docs/ARCHITECTURE.md`, `docs/DEVELOPMENT.md`, and `docs/CSV_FORMAT.md`.
-
-## P3 — Low Priority
-
-### ~~9. Add --version flag to context-stats CLI~~ ✅ Done
-**What:** Add `--version` argument to `parse_args()` that prints `cc-context-stats {version}` and exits.
-**Why:** Users can't determine installed version without running the full tool. The footer shows version but only on successful render.
-**Effort:** XS
-**Depends on:** None
-**Status:** Added `--version` / `-V` flag to `parse_args()` in `context_stats.py`. Prints `cc-context-stats {__version__}` and exits. Updated help text and module docstring.