AI Context System

Appearance

Changelog ​

All notable changes to the AI Context System.

[3.5.0] - 2025-11-28 ​

Fixed - Critical Bugs & Performance Optimizations ​

Minor release addressing 6 critical bugs and 3 major performance bottlenecks discovered in production

Context: Real-world feedback from 4 production projects revealed bugs blocking workflows and performance issues affecting long-running projects. All fixes implemented with comprehensive test coverage (101/101 tests passing).

Critical Bugs Fixed (6/6) ​

BUG-1: Hardcoded Version Numbers (CRITICAL)

  • Problem: Config template had hardcoded "version": "3.0.0"
  • Impact: New installations showed wrong version, false "update available" warnings
  • Fixed: Version auto-detected from VERSION file in both /init-context and /update-context-system
  • Modules: MODULE-001, MODULE-002
  • Tests: 13/13 passing

BUG-2: zsh Parsing Error (CRITICAL)

  • Problem: Version check used bash-specific [[ ]] syntax
  • Impact: Commands failed on zsh (macOS default shell)
  • Fixed: Portable shell syntax using single [ and -lt comparison
  • Module: MODULE-003
  • Tests: 8/8 passing

BUG-3: Integer Expression Error

  • Problem: grep -c in decision count returned multiline output
  • Impact: /review-context crashed with "integer expression expected"
  • Fixed: Use wc -l instead of grep -c for reliable counting
  • Module: MODULE-004
  • Tests: 7/7 passing

BUG-4: Installation Fails on Small Files

  • Problem: Installer expected ORGANIZATION.md but many projects don't have it
  • Impact: Installation failed with HTTP 404 errors
  • Fixed: Mark ORGANIZATION.md as optional in installer
  • Module: MODULE-005
  • Tests: 4/4 passing

BUG-5: Token Limit Crash on Large SESSIONS.md (CRITICAL)

  • Problem: /review-context loaded entire SESSIONS.md file (10,000+ lines)
  • Impact: Claude Code crashed with token limit errors
  • Fixed: Smart loading strategy based on file size
    • Small (<1000 lines): Load fully
    • Medium (1000-5000 lines): Load index + recent 500 lines strategically
    • Large (>5000 lines): Load index + recent 300 lines minimally
  • Module: MODULE-006
  • Tests: 8/8 passing
  • Result: Can now handle SESSIONS.md files with 50,000+ lines

BUG-6: Commands Fail from Subdirectories (CRITICAL)

  • Problem: Commands assumed user was in project root
  • Impact: All commands failed when run from src/, tests/, etc.
  • Fixed: Auto-detect context folder by walking up directory tree
  • Module: MODULE-007
  • Tests: 6/6 passing
  • Files updated: 10+ command files with find_context_dir integration

Performance Improvements (3/3) ​

PERF-1: Large SESSIONS.md File Management

  • Problem: SESSIONS.md grows unbounded, causing slowdowns and token issues
  • Solution: Automatic session archiving system
    • MODULE-101: Core archiving logic (archive-sessions-helper.sh)
      • Archives old sessions to SESSIONS-archive-YYYY.md
      • Keeps last N sessions in main file (default: 10)
      • Creates backups before modifying
      • Idempotent (safe to run multiple times)
      • No data loss (sessions = main + archive)
    • MODULE-102: Auto-trigger in /save-full
      • Prompts user when SESSIONS.md exceeds 2000 lines
      • One-command archiving: "Archive old sessions (keep last 10)? [Y/n]"
      • Shows before/after file sizes
  • Tests: 16/16 passing
  • Impact: SESSIONS.md stays manageable, file read times reduced by 80-90%

PERF-2: Manual Report Creation Friction

  • Problem: After /code-review, user had to manually ask for report document
  • Impact: Reports lost when chat scrolled, no historical tracking
  • Solution: Auto-generate report files
    • MODULE-103: Automatic report creation
      • Creates artifacts/code-reviews/session-N-review.md automatically
      • Uses session number from SESSIONS.md
      • Includes date stamp, grade, and full analysis
      • No manual work required
  • Tests: 8/8 passing
  • Impact: Zero manual work, consistent formatting, historical tracking

PERF-3: Manual Consistency Checking

  • Problem: /review-context asked users to "check cross-document consistency" manually
  • Impact: Easy to miss discrepancies (dates, phases, session counts)
  • Solution: Automated consistency checks
    • MODULE-104: Cross-document verification in /review-context
      • Compares "Last Updated" dates across CONTEXT.md, STATUS.md, SESSIONS.md
      • Detects phase drift between CONTEXT.md and STATUS.md
      • Validates session count accuracy
      • Shows specific warnings for mismatches
  • Tests: 8/8 passing
  • Impact: Automatic drift detection, actionable warnings

Test Coverage ​

Comprehensive 3-Level Test Suite (101/101 tests passing - 100%)

  • Level 1 - Unit Tests: 78/78 passing

    • All 11 modules tested in isolation
    • Module-specific functionality verified

  • Level 2 - Integration Tests: 12/12 passing

    • Cross-module interactions verified
    • Archiving integration (MODULE-101 + MODULE-102)
    • Version detection consistency
    • Context folder detection from subdirectories
    • Bash 3.2+ compatibility confirmed

  • Level 3 - Manual Verification: 11/11 passing

    • Actual script execution validated
    • Archive script dry-run and real execution
    • Helper scripts syntax and functionality
    • All command files present and readable

Test Infrastructure:

  • 14 test files created
  • 3 test runners (unit, integration, comprehensive)
  • Shared test helpers with isolated environments
  • Zero test failures, zero regressions

Files Changed ​

New Files:

  • scripts/archive-sessions-helper.sh - Core archiving logic (~200 lines)
  • scripts/tests/test-module-001.sh through test-module-104.sh (11 files)
  • scripts/tests/run-all-tests.sh - Unit test runner
  • scripts/tests/test-integration.sh - Integration test suite
  • scripts/tests/test-manual-verification.sh - Manual verification
  • scripts/tests/run-comprehensive-tests.sh - Master test runner
  • TEST_RESULTS_v3.5.0.md - Comprehensive test documentation

Updated Files:

  • .claude/commands/init-context.md - Version auto-detection (MODULE-001)
  • .claude/commands/update-context-system.md - Version auto-detection (MODULE-002)
  • .claude/commands/review-context.md - Smart SESSIONS.md loading (MODULE-006), consistency checks (MODULE-104)
  • .claude/commands/save-full.md - Archiving auto-trigger (MODULE-102)
  • .claude/commands/code-review.md - Auto-report generation (MODULE-103)
  • 10+ command files - Context folder auto-detection (MODULE-007)
  • scripts/common-functions.sh - Version check portability (MODULE-003)

Quality Assurance ​

  • Cross-platform: bash 3.2+, bash 4.0+, zsh, sh (all verified)
  • Backward compatible: No breaking changes
  • Test-driven: All tests written BEFORE implementation
  • Zero regressions: All existing functionality intact
  • Modular: Each fix independently tested and verified

Deployment Status ​

✅ Ready for Production

  • All 11 modules implemented
  • 101/101 tests passing
  • Zero failures detected
  • Comprehensive documentation
  • No known issues

View complete test results →

[3.4.0] - 2025-11-17 ​

Added - Code Review Actionability Features ​

Minor release with major enhancement to /code-review command based on real-world user feedback from two production projects

Context: Users reported that /code-review produced excellent analysis but required 30-60 minutes of manual work to create TodoWrite tasks, update context files, and track progress between reviews.

User Impact ​

Before v3.4.0:

  1. Run /code-review
  2. Read 458-line report
  3. Manually create 40+ todos (30 min)
  4. Manually update KNOWN_ISSUES.md
  5. Manually update STATUS.md
  6. Manually compare with previous review
  7. Manually track grade progression

After v3.4.0:

  1. Run /code-review
  2. Read report
  3. Accept prompts (Y/Y/Y) → 30 seconds
  4. ✅ Auto-generated 7 grouped tasks from 42 issues
  5. ✅ Auto-updated KNOWN_ISSUES.md (3 critical)
  6. ✅ Auto-updated STATUS.md
  7. ✅ Auto-comparison: "10/12 issues resolved ✅"
  8. ✅ Grade progression tracked in INDEX.md

Time Saved: 30-60 minutes → 5 minutes per review

Features Added ​

1. Smart Issue Grouping

  • Groups 3+ similar issues into single task
  • Example: 25 "missing type definition" errors → 1 grouped task
  • Impact: 40+ tasks → 7-10 actionable tasks

2. Automatic TodoWrite Task Generation

  • Auto-generates tasks from findings with severity threshold filtering
  • Smart formatting for grouped vs individual tasks
  • Impact: 30 minutes → 30 seconds (user accepts prompt)

3. KNOWN_ISSUES.md Integration

  • Auto-adds CRITICAL/HIGH issues to KNOWN_ISSUES.md
  • Bidirectional links (review ↔ issues)
  • Impact: Future AI sessions see critical issues without re-reading review

4. STATUS.md Auto-Update

  • Auto-adds review summary under "Recent Changes"
  • Grade, issue counts, and link to full report
  • Impact: Project status shows current quality at a glance

5. Review History Tracking

  • Tracks all reviews in artifacts/code-reviews/INDEX.md
  • Tabular format showing quality trends over time
  • Impact: Visible quality progression (C → B → A → A+)

6. Automatic Review Comparison

  • Auto-detects and compares with previous review
  • Shows resolved/new/persistent issues
  • Impact: "10/12 issues resolved ✅" shown automatically

New Files ​

  • scripts/code-review-helpers.sh - Modular helper library (578 lines, 8 functions)
  • scripts/tests/test-code-review-helpers.sh - Comprehensive test suite (33 tests)
  • scripts/tests/sample-review-issues.json - Test data
  • scripts/tests/test-upgrade-path.sh - Upgrade validation (19 tests)

Updated Files ​

  • .claude/commands/code-review.md - Added Step 8: Integration & Actionability (+278 lines)
  • install.sh - Added new files, jq dependency check, feature announcements
  • VERSION - Bumped to 3.4.0
  • CHANGELOG.md - Complete v3.4.0 entry

Dependencies ​

  • New requirement: jq for JSON processing
  • Installation: brew install jq (macOS) or apt-get install jq (Linux)

Test Coverage ​

  • Helper functions: 33/33 tests passing ✓
  • Upgrade path: 19/19 tests passing ✓
  • All tests passing before integration (TDD approach)

View full changelog on GitHub →

[3.3.1] - 2025-11-16 ​

Fixed - Emergency Bug Fixes & Installer Improvements ​

Patch release addressing critical installation reliability issues and command execution bugs discovered during real-world testing

Installer Improvements ​

Missing Helper Scripts (CRITICAL)

  • Fixed: find-context-folder.sh and update-quick-reference.sh not included in installation
  • Impact: Commands failed with "script not found" when run from subdirectories
  • Now: Both scripts automatically installed and verified

Version Sync Portability

  • Fixed: sed -i behaves differently on macOS vs Linux
  • Impact: Version could get out of sync between VERSION file and config
  • Now: Portable implementation using temp files, works on all platforms

Download Retry Logic

  • Added: Automatic retry with exponential backoff (3 attempts, 2s/4s delays)
  • Impact: Network hiccups and GitHub rate limiting no longer cause installation failures
  • Now: Robust installation even with intermittent connectivity

Post-Installation Validation

  • Added: Automatic validation with auto-repair after installation
  • Checks: Version sync, script permissions
  • Impact: Issues caught and fixed immediately, not discovered later
  • Philosophy: Prevention over repair

Enhanced Backup & Rollback

  • Added: VERSION file and context/ directory to backup/rollback
  • Impact: Complete system restoration on installation failure
  • Now: Zero data loss from failed installations

Command Fixes ​

Bash Parsing Errors in /save and /save-full (CRITICAL)

  • Fixed: Multi-line bash if-then-else blocks caused parsing errors in Claude Code
  • Error: parse error near 'then', parse error near '&&'
  • Impact: /save command failed during git status extraction
  • Now: Simple sequential commands with graceful fallback
  • Discovered: User testing in real project (excellent feedback loop!)

Testing & Documentation ​

Comprehensive Test Suite

  • Added: 15 automated tests covering all bug fixes (15/15 passing)
  • Coverage: Counter removal, helper scripts, version sync, retry logic, validation, backup/rollback

Pattern Documentation

  • Added: Bash command pattern guidelines for future development
  • Documents: Anti-patterns to avoid, recommended alternatives, testing checklist

Sprint Report

  • Added: Complete implementation documentation with code examples and lessons learned

Removed ​

Cleanup

  • Removed: Unused counter fields from config template (dead code)

Implementation Philosophy ​

  • Prevention over band-aids: Post-installation validation catches issues immediately
  • Modularity: Each fix implemented as testable function
  • Real-world validation: User discovered bash parsing errors during actual usage

View full changelog on GitHub →

[3.3.0] - 2025-11-13 ​

Added - Template Protection & Documentation Currency ​

Major release with 5 features based on 100+ production session feedback

Features Added ​

1. Template Markers (Template Protection)

  • HTML comment markers protect critical template sections
  • <!-- TEMPLATE SECTION: KEEP ALL --> preserves structure and content
  • <!-- TEMPLATE: READ-ONLY --> marks instructional files
  • [FILL: description] provides clear placeholders
  • Impact: Prevents 80-90% of template deletion errors

2. Deletion Protection

  • Interactive confirm_deletion() function with file details
  • Requires explicit "yes" confirmation before deletion
  • Default: keep file (safe by default)
  • Impact: Zero data loss from accidental deletions

3. Documentation Staleness Detection

  • /save-full warns when CONTEXT.md is >7 days old, README.md >14 days old
  • /review-context shows color-coded staleness (🟢🟡🔴) for all context/*.md files
  • Detects missing module READMEs
  • Impact: Prevents documentation drift before it becomes a problem

4. Decision Documentation Guidance

  • Added comprehensive guidance to claude.md template
  • 5 decision categories with examples (Library/Framework, Performance, Data Model, Security, Process)
  • DECISIONS.md format example with metrics
  • Impact: Better architectural decision capture and context preservation

5. Upgrade Path Documentation

  • "What's New in v3.3.0" section in update-guide.md
  • /update-context-system displays features after upgrade
  • Clear adoption guidance for each feature
  • Impact: Users understand new features and how to use them

Test Coverage ​

  • 69/69 tests passing (100% pass rate)
  • 13 files changed
  • ~2,000+ lines of code, tests, and documentation

View full changelog on GitHub →

[3.2.2] - 2025-10-23 ​

Fixed - Critical Installer Bugs ​

Emergency patch fixing installer bugs blocking all upgrades

Critical Bugs Fixed ​

BUG-003: Deprecated Command in Installer (CRITICAL)

  • Installer tried to download removed save-context.md
  • Caused HTTP 404 errors, 100% upgrade failure rate
  • Fixed: Removed from installer command list

BUG-004: Version Detection Returns Blank

  • Showed blank instead of current version
  • Fixed: Priority-order detection (VERSION file → config → scripts)

BUG-005: Misleading Error Message (CRITICAL UX)

  • Showed "Installation successful!" then "Installation failed!"
  • 100% user confusion in non-interactive mode
  • Fixed: Disabled ERR trap after success, skip prompts with --yes

View full changelog on GitHub →

[3.2.1] - 2025-10-22 ​

Fixed - Critical Dogfooding Feedback ​

Patch release addressing issues found during real-world testing

Critical Bugs Fixed ​

BUG-001: Session Number Detection

  • Helper script counted template sessions as real sessions
  • Detected "Session 6" for first-ever session
  • Fixed: Updated pattern to exclude templates

BUG-002: Context Folder Detection

  • Commands assumed correct directory, failed from subdirectories
  • Fixed: Integrated find-context-folder.sh logic

CRITICAL: Quick Reference Auto-Generation NOT Implemented

  • Documentation said "auto-generated" but was manual
  • FALSE ADVERTISING - 15+ fields required manual work
  • Fixed: Created update-quick-reference.sh script

[3.2.0] - 2025-10-20 ​

Added - Rebrand to "AI Context System" ​

Major rebrand from "Claude Context System" to "AI Context System"

  • System name: Claude Context System → AI Context System
  • Repository: claude-context-system → ai-context-system
  • Multi-AI support emphasized
  • Tool-specific headers (claude.md, cursor.md, aider.md)

Earlier Versions ​

See full changelog on GitHub for complete version history.