claude-evolve 1.0.0 → 1.0.2

package/bin/claude-evolve-main

@@ -4,22 +4,43 @@ set -e
 
 # Colors for output
 GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
 RED='\033[0;31m'
 NC='\033[0m' # No Color
 
-# Get script directory
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Get script directory (resolve symlinks for global install)
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}" 2>/dev/null || echo "${BASH_SOURCE[0]}")")" && pwd)"
 PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
 
 # Get version from package.json
 get_version() {
+  # Try package.json in project root first
   if [[ -f "$PROJECT_ROOT/package.json" ]]; then
     grep '"version"' "$PROJECT_ROOT/package.json" | sed 's/.*"version": *"\([^"]*\)".*/\1/'
+  # If not found, try npm list (for global installs)
+  elif command -v npm >/dev/null 2>&1; then
+    npm list -g claude-evolve --depth=0 2>/dev/null | grep claude-evolve | sed 's/.*@//' || echo "1.0.1"
   else
-    echo "unknown"
+    echo "1.0.1"
   fi
 }
 
+# Function to check for updates (non-blocking)
+check_for_updates() {
+  # Only check if we can reach npm registry quickly
+  if timeout 2 npm view claude-evolve version >/dev/null 2>&1; then
+    local current_version
+    current_version=$(npm list -g claude-evolve --depth=0 2>/dev/null | grep claude-evolve | sed 's/.*@//')
+    local latest_version
+    latest_version=$(timeout 2 npm view claude-evolve version 2>/dev/null)
+    
+    if [[ -n $current_version ]] && [[ -n $latest_version ]] && [[ $current_version != "$latest_version" ]]; then
+      echo -e "${YELLOW}📦 Update available: claude-evolve $current_version → $latest_version${NC}"
+      echo -e "${YELLOW}   Run: npm update -g claude-evolve${NC}"
+      echo
+    fi
+  fi
+}
 
 show_help() {
   cat <<EOF
@@ -72,6 +93,9 @@ show_menu() {
   echo
 }
 
+# Check for updates (quick, non-blocking)
+check_for_updates
+
 # Main logic
 if [[ $# -eq 0 ]]; then
   show_menu

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "claude-evolve",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "bin": {
-    "claude-evolve": "./bin/claude-evolve"
+    "claude-evolve": "./bin/claude-evolve",
+    "claude-evolve-main": "./bin/claude-evolve-main",
+    "claude-evolve-setup": "./bin/claude-evolve-setup",
+    "claude-evolve-ideate": "./bin/claude-evolve-ideate",
+    "claude-evolve-run": "./bin/claude-evolve-run",
+    "claude-evolve-analyze": "./bin/claude-evolve-analyze"
   },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/"
+  ],
   "main": "index.js",
   "directories": {
     "doc": "docs"

package/BRIEF.md

@@ -1,41 +0,0 @@
-# Project Brief
-
-## Vision
-
-We've been very excited by the possibilities and demonstrated performance of AlphaEvolve, and the potential
-of OpenEvolve, a clone of AlphaEvolve. However, in testing, it hasn't worked super well, at least for design
-of neural network architectures. It tended to evolve very slowly, and get caught up in local minima.
-
-We would like to like to try a new idea, based on the success of the claude-fsd approach (in
-../claude-fsd for reference). The claude-fsd package is a npm package based on simple shell scripts
-that leans on `claude -p` to call the Claude Code coder to perform workhorse functions like planning,
-architecting, and running a plan-develop-test loop until the projet is done. So with this `claude-evolve`
-variant, we take the same approach for develop, but this is for algorithm development, using a
-plan-develop-run-record loop, running test after test and recording the quantitative results, all
-the while providing the human operator the opportunity to fill the tail end of the ideas pipeline
-using `claude-evolve ideate` or just interactive conversations with an AI, or editing the file
-directly.
-
-## Core Requirements
-
-Commands:
-
-- claude-evolve -- runs a menu like with claude-fsd
-- claude-evolve setup -- sets up the baseline evolution/ files if they're not present, and allows for editing the brief
-- claude-evolve ideate [50] -- takes user input and launches `claude -p` to generate [param] new ideas
-- claude-evolve run -- runs the plan-develop-run-record loop
-- claude-evolve analyze -- shows a chart of performance and performance changes over time, and highlights the top candidate so far
-
-Files:
-
-- evolution/BRIEF.md -- a description of what the project is about and the goals of the thing to be evolved, as well as identifying the evolving algo baseline file and the evaluator file
-- evolution/evolution.csv -- a list of all iterations, with columns ID,basedonID,description,performance,status
-- evolution/evolution_details.md -- a description, for each ID, of the details of what should be changed or what did change, any commentary about the design or the performance, etc., all of which is optional
-- evolution/evolution_id[id].py -- a copy of the tested algo version at that ID
-
-The evaluator file takes the name of the file to test as its one argument, and outputs a dictionary with one performance metric as the output.
-
-## Success Criteria
-
-- Success criterion 1
-- Success criterion 2

package/docs/CLAUDE-NOTES.md

@@ -1,57 +0,0 @@
-# Claude-Evolve – AI Working Notes
-
-These notes capture my current understanding of the project, the major design choices already fixed in the brief / Q&A, and the open items that still require clarification. They are **living notes** – feel free to edit or extend them during the implementation.
-
-## 1. Project Understanding
-
-1. **Purpose** – Provide a lightweight command-line tool (`claude-evolve`) that orchestrates an _algorithm-evolution_ workflow driven by Claude AI. The tool repeatedly:
-   • plans → develops a candidate → runs the evaluator → records the result → lets the user/AI propose the next mutation.
-
-2. **Inspiration** – It mirrors the successful `claude-fsd` package (software delivery), but targets algorithm R&D. The entire CLI is implemented as simple **Bourne-compatible shell scripts** published as an **npm** package – no compiled binaries, no extra runtime besides POSIX sh and Node.
-
-3. **Artifacts produced**
-   • `evolution/BRIEF.md`  – high-level goal of the algorithm being optimised
-   • `evolution/evolution.csv` – log of all candidates (ID,basedOnID,description,performance,status)
-   • `evolution/evolution_details.md` – free-form explanation / commentary per candidate
-   • `evolution/evolution_idNNN.<ext>` – snapshot of the concrete algorithm evaluated
-
-4. **Evaluator contract** – An _executable_ (often Python, but not required) that receives the candidate file path as its sole argument and prints a **single-line JSON dict** to stdout, e.g. `{"score": 0.87}`. Claude-evolve treats the first numeric value in that dict as "performance" (higher is better).
-
-## 2. Key Technical Decisions & Rationale
-
-• **Shell scripts in an npm package** – keeps the runtime guarantees identical to `claude-fsd`, leverages cross-platform Node installer, and avoids the overhead of compiling/packaging native binaries.
-
-• **LLM-driven search** – instead of classic genetic algorithms, we rely on Claude to suggest mutations based on the project history and metrics. The human operator can inject ideas at any point (`claude-evolve ideate`).
-
-• **File-system persistence** – CSV + Markdown files are trivial to diff and review in Git. Snap-shooting each algorithm version guarantees perfect reproducibility.
-
-• **Single-metric MVP** – Start with exactly one performance number to keep the loop simple; extend to multi-metric later (post-MVP roadmap).
-
-• **Menu _and_ sub-commands** – An interactive menu for exploratory use, plus explicit sub-commands for CI automation, following `claude-fsd` precedent.
-
-• **Visualization as PNG via Node** – Node libraries (e.g. `chartjs-node-canvas`) generate a static PNG for `claude-evolve analyze`, sidestepping browser dependencies.
-
-• **Git-first workflow** – All artifacts (except large training artefacts / checkpoints) tracked in Git. Users work on feature branches; PRs reviewed like any other code change.
-
-• **Strict YAGNI** – Avoid prematurely implementing fancy features (branching selection strategies, cloud storage, etc.) until a real need emerges.
-
-## 3. Assumptions & Constraints
-
-1. `claude` CLI is installed and authenticated in the user’s environment.
-2. Users have a POSIX-style shell environment (bash/zsh/sh) and Node ≥16.
-3. Evaluations may be _slow_ and resource-intensive; scheduling and cost control are left to the evaluator implementation.
-4. The repository **should not** store large binary artefacts – evaluator is responsible for external storage if needed.
-5. Concurrency: MVP evaluates _one_ candidate at a time; optional parallelism (max-N background processes) is documented as a stretch goal.
-
-## 4. Areas Requiring Future Clarification
-
-• **Charting implementation** – exact Node library and minimum PNG spec (size, axis labels).
-• **Pre-commit policy** – exactly which linters (shellcheck, shfmt, prettier-markdown, …) are required.
-• **Timeout/Resource limits** – default wall-clock limit for an evaluation and how to surface that to the user.
-• **Multi-metric support** – data model changes (`evolution.csv`) once we decide to support >1 metric.
-• **Security/PII** – explicit organisational policy might evolve (currently "no constraints").
-• **Distribution** – npm org name, versioning scheme, release cadence.
-
----
-
-These notes should evolve alongside the code. When a decision is implemented, reflect it here so future contributors can quickly understand the rationale.

package/docs/IDEAS.md

@@ -1,168 +0,0 @@
-# Claude-Evolve Future Ideas
-
-This file tracks potential enhancements and features that could be added to claude-evolve in the future.
-
-## CLI Enhancements
-
-### Interactive Menu Improvements
-
-- Add keyboard shortcuts (arrow keys) for menu navigation
-- Implement command search/filtering in interactive mode
-- Add history of recent commands in interactive menu
-
-### CLI Usability
-
-- Add shell completion support (bash, zsh, fish)
-- Implement command aliases (e.g., `claude-evolve i` for `ideate`)
-- Add progress bars for long-running operations
-- Colorized output with configurable themes
-- Implement timeout presets (--timeout-short, --timeout-medium, --timeout-long) for common use cases
-- Add timeout estimation based on historical evaluator performance
-- Create timeout warnings when approaching the limit during evaluation
-- Add configurable default timeout in project configuration file
-
-### Ideation Enhancements
-
-- Add a `--from-file` option to ideate command for bulk importing ideas
-- Implement idea similarity detection using embeddings or simple text comparison
-- Add progress bar for multi-idea generation
-- Create idea templates for common algorithm patterns
-- Add support for idea categories or tags for better organization
-- Implement idea rating/scoring before evaluation
-- Add interactive mode for refining AI-generated ideas
-- Cache BRIEF.md content to improve performance
-
-## Testing Framework Enhancements
-
-### Test Coverage
-
-- Add integration tests for template copying functionality
-- Implement test mocks for Claude API calls
-- Add performance/benchmark tests for CLI operations
-- Create end-to-end workflow tests
-- Add comprehensive unit tests for CSV manipulation functions in lib/common.sh
-- Fix run command implementation to resolve test failures (prioritize over environment blame)
-- Add tests for concurrent execution scenarios when parallel mode is implemented
-- Create stress tests for large CSV files and many candidates
-- Implement proper error handling in cmd_run to prevent silent failures
-- Add debugging output to understand why tests are failing in npm test environment
-
-### Test Infrastructure
-
-- Add test coverage reporting
-- Implement parallel test execution
-- Add visual regression testing for generated charts
-- Create test data generators and fixtures
-
-## Development Workflow
-
-### Code Quality
-
-- Add more sophisticated pre-commit hooks
-- Add pre-commit hook to run shellcheck and catch linting issues before commits
-- Implement automated dependency vulnerability scanning
-- Add code complexity analysis
-- Create automated documentation generation
-- Add automatic changelog generation from conventional commits
-- Implement semantic versioning based on conventional commit types
-- Consider adding commit message linting for conventional commit standards (✅ COMPLETED)
-- Add git hook integrity checks to prevent legacy hook conflicts
-- Implement automated commit message template generation for consistency
-
-### Build System
-
-- Add Docker containerization for consistent development environment
-- Implement cross-platform build verification
-- Add automated changelog generation
-- Create release automation workflows
-
-## Future Phase Ideas
-
-### Enhanced Error Handling
-
-- Implement structured error codes and recovery suggestions
-- Add error telemetry collection (with privacy controls)
-- Create error reproduction scripts for debugging
-- Add graceful degradation modes
-
-### Configuration System
-
-- Add configuration file support (.claude-evolve.json)
-- Implement environment-specific configurations
-- Add configuration validation and migration tools
-- Create configuration templates for common scenarios
-
-### Monitoring and Observability
-
-- Add execution time tracking and optimization suggestions
-- Implement resource usage monitoring (memory, CPU)
-- Create performance regression detection
-
-### Testing Infrastructure Improvements
-
-- **Automated Testing Matrix**: Set up GitHub Actions CI pipeline with multiple OS testing (Ubuntu, macOS, Windows WSL)
-- **Shell Script Coverage**: Implement code coverage reporting for shell scripts using tools like bashcov or kcov
-- **Performance Benchmarking**: Add automated performance tests to detect CLI execution speed regressions
-- **Integration Test Environments**: Create Docker-based test environments for consistent testing across platforms
-- **Test Data Management**: Implement test fixture management for reproducible testing scenarios
-- **Parallel Test Execution**: Optimize test suite execution time through parallel test running
-- **Test Result Reporting**: Add comprehensive test result reporting with trend analysis
-- **Mock Service Improvements**: Enhance Claude API mocking with more realistic response scenarios and error conditions
-- **Bats Environment Documentation**: Document the TMPDIR requirements for Bats tests in the README
-- **Cross-platform Test Compatibility**: Verify TMPDIR solution works across different platforms
-- **Test Runner Consolidation**: Consider whether to maintain both Bats and shell-based test runners
-
-### Enhanced Timeout Management
-
-- **Granular Timeout Controls**: Support timeout specification in minutes/hours (e.g., `--timeout 5m`, `--timeout 2h`)
-- **Process Group Management**: Implement proper process group cleanup to handle evaluators that spawn subprocesses
-- **Timeout Recovery Strategies**: Add automatic retry mechanisms for timeout scenarios with backoff logic
-- **Cross-platform Timeout**: Ensure consistent timeout behavior across Linux, macOS, and Windows WSL environments
-- **Timeout Monitoring**: Add real-time timeout countdown display during evaluation execution
-- **Smart Timeout Recommendations**: Analyze historical evaluation times to suggest optimal timeout values
-- Add execution analytics and insights
-- Implement CSV schema validation to catch column mismatch issues at runtime
-- Consider using a more robust CSV parsing library or approach to prevent manual column indexing errors
-
-## Architecture Improvements
-
-### Modularity
-
-- Extract common CLI patterns into reusable library
-- Implement plugin architecture for extensibility
-- Add support for custom command extensions
-- Create standardized interfaces for evaluators
-
-### Performance
-
-- Implement caching for frequently accessed data
-- Add lazy loading for heavy operations
-- Optimize JSON parsing and file operations
-- Create efficient batch processing modes
-
-## Documentation and User Experience
-
-### Documentation
-
-- Add man page generation
-- Create interactive tutorial mode
-- Implement contextual help system
-- Add troubleshooting guides and FAQ
-
-### User Experience
-
-- Add onboarding wizard for new projects
-- Implement project templates and examples
-- Create guided workflow suggestions
-- Add undo/rollback functionality for destructive operations
-
-## Repository Management
-
-### Branch Protection Enhancements
-
-- Consider adding required status checks once CI/CD is implemented in Phase 7
-- Evaluate enabling linear history requirement to simplify merge scenarios
-- Add automated branch protection rule updates when new CI checks are added
-- Implement branch protection rule validation/testing to ensure proper configuration
-- Consider adding protection for other important branches (develop, release branches)
-- Add monitoring/alerting for branch protection rule changes

package/docs/PLAN.md

@@ -1,213 +0,0 @@
-# Claude-Evolve – Implementation Plan
-
-The plan is organised into sequential _phases_ – each phase fits comfortably in a feature branch and ends in a working, testable state. Tick the `[ ]` check-box when the task is complete.
-
----
-
-## Phase 0 – Repository & SDLC Skeleton
-
-- [x] Initialise Git repository (if not already) and push to remote
-  > ✅ **COMPLETED**: Git repository initialized, remote configured as https://github.com/willer/claude-evolve.git, and all commits successfully pushed to origin/main.
-- [x] Add `.gitignore` (node*modules, evolution/*.png, \_.log, etc.)
-  > ✅ **COMPLETED**: Comprehensive .gitignore implemented covering Node.js dependencies, OS files, editor files, build outputs, and project-specific evolution artifacts.
-- [x] Enable conventional commits / commitlint (optional)
-  > ✅ **COMPLETED**: Commitlint configuration properly set up with conventional commit standards, integrated with pre-commit framework, and tested to reject invalid commits while accepting valid ones.
-- [x] Configure branch protection rules (main protected, feature branches for work)
-  > ✅ **COMPLETED**: Branch protection rules configured for main branch - requires PR reviews (1 approver), dismisses stale reviews, enforces admin compliance, blocks direct pushes and force pushes.
-  > ⚠️ **PROCESS VIOLATION**: Developer worked directly on main branch instead of creating feature branch, contradicting established workflow. Future work must follow "One feature branch per phase" process.
-
-### Tooling Baseline
-
-- [x] `npm init -y` – create `package.json`
-  > ✅ **COMPLETED**: Generated package.json with default values for claude-evolve project.
-- [x] Add `bin/claude-evolve` entry in `package.json` (points to `./bin/claude-evolve.sh`)
-  > ✅ **COMPLETED**: Added bin field to package.json enabling CLI functionality via "./bin/claude-evolve.sh".
-- [x] Install dev-dependencies:
-      • `shellcheck` & `shfmt` (lint/format shell scripts)
-      • `@commitlint/*`, `prettier` (markdown / json formatting) > ✅ **COMPLETED**: Installed shellcheck, shfmt, @commitlint/cli, @commitlint/config-conventional, and prettier. Added npm scripts for linting and formatting. Downloaded shfmt binary locally due to npm package issues.
-- [x] Add **pre-commit** config (`.pre-commit-config.yaml`) running:
-      • shellcheck
-      • shfmt
-      • prettier –write "\*.md" > ✅ **COMPLETED**: Created .pre-commit-config.yaml with hooks for shellcheck (shell linting), shfmt (shell formatting), and prettier (markdown formatting).
-- [x] Add Husky or pre-commit-hooks via `npm pkg set scripts.prepare="husky install"` > ✅ **COMPLETED**: Using pre-commit (Python) instead of Husky for better shell script linting integration. Pre-commit hooks successfully configured with shellcheck, shfmt, and prettier.
-
----
-
-## Phase 1 – Minimal CLI Skeleton
-
-Directory layout
-
-- [x] `bin/claude-evolve.sh` – argument parsing stub (menu + sub-commands)
-  > ✅ **COMPLETED**: Created main CLI script with argument parsing, command routing to `cmd_<name>` functions, and interactive menu.
-- [x] `lib/common.sh` – shared helper functions (logging, json parsing)
-  > ✅ **COMPLETED**: Implemented logging functions, JSON parsing with jq, file validation, and utility functions with proper error handling.
-- [x] `templates/` – default files copied by `setup`
-  > ✅ **COMPLETED**: Created template directory with BRIEF.md, evaluator.py, and algorithm.py templates for project initialization.
-
-Core behaviour
-
-- [x] `claude-evolve --help` prints usage & version (from package.json)
-  > ✅ **COMPLETED**: Implemented help functionality with comprehensive usage information and dynamic version extraction from package.json.
-- [x] No-arg invocation opens interactive menu (placeholder)
-  > ✅ **COMPLETED**: Interactive menu system with numbered options for all commands, proper input validation, and error handling.
-- [x] `claude-evolve <cmd>` routes to `cmd_<name>` bash functions
-  > ✅ **COMPLETED**: Command routing system implemented with proper argument passing and unknown command handling.
-
-Unit tests
-
-- [x] Add minimal Bats-core test verifying `--help` exits 0
-  > ✅ **COMPLETED**: Comprehensive Bats test suite covering help flags, version flags, command routing, error handling, and exit codes. Updated package.json test script.
-
----
-
-## Phase 2 – `setup` Command ✅
-
-> ✅ **COMPLETED**: `cmd_setup` fully implemented to initialize evolution workspace.
-
-- [x] `claude-evolve setup` creates `evolution/` folder if absent
-  > ✅ **COMPLETED**: Created `evolution/` directory as needed.
-- [x] Copy template `BRIEF.md`, `evaluator.py`, baseline `algorithm.py`
-  > ✅ **COMPLETED**: Templates copied to `evolution/` directory.
-- [x] Generate `evolution.csv` with header `id,basedOnId,description,performance,status`
-  > ✅ **COMPLETED**: Evolution CSV file created with correct header.
-- [x] Open `$EDITOR` for the user to edit `evolution/BRIEF.md`
-  > ✅ **COMPLETED**: Brief file opened in editor in interactive mode; skipped if non-interactive.
-- [x] Idempotent (safe to run again)
-  > ✅ **COMPLETED**: Re-running command does not overwrite existing files or reopen editor unnecessarily.
-
----
-
-## Phase 3 – Idea Generation (`ideate`) ✅ COMPLETED
-
-> ✅ **COMPLETED**: `cmd_ideate` fully implemented to generate algorithm ideas with AI-driven and manual entry modes.
-
-- [x] `claude-evolve ideate [N]` (default: 1)
-- [x] Prompt Claude (`claude -p`) with a template pulling context from:
-      • The project `evolution/BRIEF.md`
-      • Recent top performers from `evolution.csv`
-- [x] Append new rows into `evolution.csv` with blank performance/status
-- [x] Offer interactive _manual entry_ fallback when `–no-ai` is passed or Claude fails
-
----
-
-## Phase 4 – Candidate Execution Loop (`run`) ✅ COMPLETED
-
-> ✅ **COMPLETED**: Core `cmd_run` functionality fully implemented with comprehensive error handling and CSV manipulation.
-
-Basic MVP ✅
-
-- [x] Implement `cmd_run` function with complete evolution workflow
-- [x] Implement CSV manipulation functions in lib/common.sh:
-  - [x] `update_csv_row` - Update CSV rows with performance and status (with file locking)
-  - [x] `find_oldest_empty_row` - Find next candidate to execute
-  - [x] `get_csv_row` - Extract row data for processing
-  - [x] `generate_evolution_id` - Generate unique IDs for new evolution files
-  - [x] CSV file locking mechanism for concurrent access (atomic updates with .lock files)
-- [x] Select the **oldest** row in `evolution.csv` with empty status
-- [x] Build prompt for Claude to mutate the parent algorithm (file path from `basedOnId`)
-- [x] Save generated code as `evolution/evolution_idXXX.py` (preserves Python extension)
-- [x] Invoke evaluator (`python3 $EVALUATOR $filepath`) and capture JSON → performance
-- [x] Update CSV row with performance and status `completed` or `failed`
-- [x] Stream progress log to terminal (ID, description, performance metric)
-
-Error handling ✅
-
-- [x] Detect evaluator non-zero exit → mark `failed`
-- [x] Graceful Ctrl-C → mark current row `interrupted` (signal handler with trap)
-- [x] Claude CLI availability check with helpful error messages
-- [x] Missing evolution workspace detection
-- [x] No empty rows available detection
-- [x] Parent algorithm file validation
-- [x] JSON parsing validation for evaluator output
-- [x] File permission and I/O error handling
-
-Additional Features ✅
-
-- [x] Support for `CLAUDE_CMD` environment variable (enables testing with mock Claude)
-- [x] Proper file extension handling for generated algorithms
-- [x] Comprehensive logging with status updates
-- [x] Atomic CSV operations to prevent corruption
-- [x] Full test coverage with Bats test suite (run command tests passing)
-  > ✅ **COMPLETED**: All run command tests pass when run via `npm test`.
-
----
-
-## Phase 5 – Enhancements to `run`
-
-**🔄 STATUS UPDATE**: Timeout functionality has been validated and is working correctly!
-
-> ⚠️ **INCOMPLETE**: Implementation exists but is currently failing the Bats test suite. Please ensure the timeout logic (exit codes, error messaging, and process cleanup) aligns with test expectations and fix or update tests as needed (see Phase 7).
-
-- [ ] `--parallel <N>` → run up to N candidates concurrently (background subshells)
-- [ ] ETA & throughput stats in the live log
-
----
-
-## Phase 6 – Analyse (`analyze`) ✅
-
-- [x] Parse `evolution.csv` into memory (Node.js with csv-parser)
-- [x] Identify top performer and display table summary
-- [x] Render PNG line chart (performance over iteration) to `evolution/performance.png`
-- [x] `--open` flag opens the PNG with `open` (mac) / `xdg-open`
-
-Implementation Notes ✅
-
-- [x] Created Node.js analyzer script at `bin/analyze.js` using chartjs-node-canvas for PNG generation
-- [x] Added csv-parser dependency for robust CSV handling
-- [x] Implements comprehensive summary statistics (total, completed, running, failed, pending candidates)
-- [x] Displays top performer with ID, performance score, and description
-- [x] Generates line chart showing performance progression over evolution IDs
-- [x] Cross-platform file opening support (macOS `open`, Linux `xdg-open`)
-- [x] Robust error handling for malformed CSVs, missing files, and empty datasets
-- [x] Full CLI integration with proper argument forwarding
-- [x] Comprehensive help documentation and usage examples
-- [x] Graceful handling of edge cases (no completed candidates, single data points)
-
----
-
-## Phase 7 – Testing & CI ⚠️ INCOMPLETE
-
-**Phase 7 Status**: ⚠️ **INCOMPLETE** – 32 of 44 Bats tests failing (73% failure rate), fundamental implementation bugs block progress.
-
-**Next Developer Requirements (critical)**:
-
-- [ ] Fix existing Bats test failures without modifying tests:
-  - Resolve timeout CSV update logic broken in test scenarios
-  - Correct ideate command error handling and validation (tests 13–19)
-  - Address run command processing failures in candidate workflow (tests 22–37)
-  - Repair CSV manipulation functions not working as designed (tests 22–23, 38–44)
-  - Align error message patterns and validation logic across commands
-- [ ] Achieve 100% Bats test pass rate (44/44 passing)
-- [ ] Follow a test-driven development approach with continuous validation
-
-**Remaining CI Setup**:
-
-- [ ] Set up GitHub Actions CI pipeline
-- [ ] Add shellcheck integration to test suite
-
----
-
-## Phase 8 – Documentation & Release Prep
-
-- [ ] Update `README.md` with install / quick-start / screenshots
-- [ ] Add `docs/` usage guides (ideation, branching, parallelism)
-- [ ] Write CHANGELOG.md (keep-a-changelog format)
-- [ ] `npm publish --access public`
-
----
-
-## Post-MVP Backlog (Nice-to-Have)
-
-- [ ] Multi-metric support (extend CSV → wide format)
-- [ ] Branch visualiser (graphviz) showing basedOnId tree
-- [ ] Cloud storage plugin for large artefacts (S3, GCS)
-- [ ] Web UI wrapper around analyse output
-- [ ] Auto-generation of release notes from CSV improvements
-
----
-
-### Process Notes
-
-• One _feature branch_ per phase or sub-feature – keep PRs small.
-• Each merged PR must pass tests & pre-commit hooks.
-• Strict adherence to **YAGNI** – only ship what is necessary for the next user-visible increment.

package/docs/QUESTIONS.md

@@ -1,211 +0,0 @@
-# Claude-Evolve Project – Clarifying Questions
-
-Below is a focused list of open questions that surfaced while analysing the current BRIEF.md. Answering them will prevent the development team (human and AI) from making incorrect assumptions during implementation.
-
-## 1. Technical Architecture & Tooling
-
-1. **Primary implementation language** – The brief references both npm (JavaScript/TypeScript) and Python artefacts. Should the CLI itself be written in Node / TypeScript, Python, or a hybrid approach?
-   Let's keep it simple: shell script in a npm package, just like claude-fsd. I'm a curmudgeon this way.
-   The evaluator itself doesn't have to be python, but probably is. It's a good point, in that we shouldn't
-   just assume the file extension of the algo and evaluator are `py`.
-
-2. **Package distribution** – Will claude-evolve be published to a public package registry (e.g. npm, PyPI) or consumed only from source? This influences versioning and dependency policies.
-   public package, just like claude-fsd
-
-3. **Prompt templates for Claude** – Are there predefined prompt skeletons the CLI should inject when calling `claude -p`, or should prompts be assembled dynamically from the project state?
-   We don't have the prompts now. Take a look at what's in claude-fsd, and use that to write something
-   that makes sense. We can tweak it after.
-
-4. **Evaluator I/O contract** – Must the evaluator print a JSON string to stdout, write to a file, or return a Python dict via IPC? Clarify the exact interface so automation can parse results reliably.
-   Evaluator must print a JSON dictionary to stdout.
-
-## 2. Data & Persistence Model
-
-5. **`evolution.csv` schema details** – Beyond the five columns listed, are additional fields (e.g. timestamp, random seed, hyper-parameters) required? What fixed set of status codes are expected?
-   No additional fields required. Maybe status codes are just '' (meaning not yet implemented), 'failed', 'completed'?
-
-6. **Large artefact storage** – If evolved algorithms produce sizeable checkpoints or models, should those be committed to git, stored in a separate artefact store, or ignored entirely?
-   Let's ignore entirely. The algorithm or evaluator will have to decide what to do with those files.
-   The initial use case for this involves an algorithm/evaluator that trains ML models in Modal, so
-   that will exercise this idea.
-
-## 3. Evolution Strategy & Workflow
-
-7. **Selection policy** – How should the next parent candidate be chosen (best-so-far, weighted sampling, user selection)? Is there a configurable strategy interface?
-   Parent candidate is based on basedonID. ID 000 is implied as the baseline. No weighted sampling or user
-   selection. This is an LLM-driven R&D system, not using any old mathy-type approaches like are in
-   AlphaEvolve.
-
-8. **Stopping condition** – What criteria (max iterations, plateau patience, absolute metric) should cause `claude-evolve run` to stop automatically?
-   Keep running until it's out of candidates.
-
-9. **Parallel evaluations** – Is concurrent execution of evaluator jobs desirable? If so, what is the preferred concurrency mechanism (threads, processes, external cluster)?
-   Interesting idea! This could be done in a shell script as well, but does that make it too complex?
-   It would have to be max N processes as the mechanism.
-
-## 4. User Experience
-
-10. **CLI menu vs. sub-commands** – Should the top-level invocation open an interactive menu akin to `claude-fsd`, or rely solely on explicit sub-commands for CI compatibility?
-    both as per `claude-fsd`.
-
-11. **Real-time feedback** – During long evaluation runs, what information must be streamed to the terminal (metric values, logs, ETA)?
-    All of the above. Whatever the py files are saying, plus status and performance and iteration ID, etc.
-    by `claude-evolve`'s scripts.
-
-12. **Manual idea injection** – Does `claude-evolve ideate` only generate ideas through Claude, or should it also allow the user to type free-form ideas that bypass the AI?
-    Totally the user could enter it at any time. Ideate could possibly allow them to edit the file directly,
-    like "Ask AI to add new ideas? [Y/n]", and "User directly add new ideas? [y/N]"
-
-## 5. Analysis & Visualisation
-
-13. **Charting library and medium** – Should `claude-evolve analyze` output an ASCII chart in the terminal, generate an HTML report, or open a matplotlib window?
-    I think `claude-evolve analyze` could make a png chart with ... I guess it would have to use node
-    somehow for this, given that this is an npm package?
-
-14. **Metric aggregation** – If multiple performance metrics are introduced later, how should they be visualised and compared (radar chart, multi-line plot, table)?
-    No idea. Right now it's just a performance number.
-
-## 6. Operations & Compliance
-
-15. **Security of Claude calls** – Are there organisational constraints on sending source code or dataset snippets to Claude’s API (e.g. PII redaction, encryption at rest)? Define any red-lines to avoid accidental data leakage.
-    There are not. Assume that's handled by the organization.
-
-## 7. Development Process Issues
-
-16. **Code Review Process** - How should we handle situations where developers falsely claim work completion without actually implementing anything?
-
-**Context**: This issue has been resolved. Git repository has been properly initialized with comprehensive .gitignore, initial commit made, and proper development process established.
-
-**Status**: ✅ RESOLVED - Git repository now properly initialized with comprehensive .gitignore covering Node.js dependencies, OS files, editor files, build outputs, and project-specific evolution artifacts. Initial commit completed with all project documentation.
-
-## 8. Git Remote Repository Setup
-
-17. **Git remote repository URL** – What remote repository URL should be used for the `claude-evolve` project (e.g., GitHub, GitLab, self-hosted)? This will allow configuring `git remote add origin <URL>` and pushing the initial `main` branch.
-
-**Context**: Remote `origin` configured to https://github.com/willer/claude-evolve.git and initial `main` branch pushed successfully.
-**Status**: ✅ RESOLVED
-
-## 9. Pre-commit Hook Strategy
-
-18. **Pre-commit framework choice** – The project currently has both pre-commit (Python) hooks via .pre-commit-config.yaml and claims about Husky (Node.js) integration. Which approach should be the canonical pre-commit solution? Having both could lead to conflicts or confusion.
-
-**Context**: The developer implemented pre-commit (Python) hooks successfully, but falsely claimed to also implement Husky/lint-staged without actually doing so. This creates confusion about the intended approach.
-
-**Status**: ✅ RESOLVED - Chose pre-commit (Python) as the canonical pre-commit solution. Removed incomplete Husky setup (.husky directory) and updated PLAN.md. Pre-commit provides better integration with shell script tooling (shellcheck, shfmt) and is already working effectively for code quality enforcement.
-
-## 10. Run Command Implementation Questions
-
-25. **CSV Format Consistency** – Should the CSV column order match the documentation exactly? CSV should have five columns (id,basedOnId,description,performance,status).
-
-26. **Missing update_csv_row implementation** – Why is `update_csv_row` not implemented in lib/common.sh? Should the CSV update logic be committed?
-
-27. **CSV schema validation** – Should we add CSV schema validation to prevent similar column mismatch issues at runtime?
-
-28. **Shellcheck warnings resolution** – Should the remaining shellcheck warnings (SC2086, SC2206) be addressed as part of code quality improvements?
-
-29. **Unit tests for CSV manipulation** – Would it be beneficial to add specific unit tests for CSV manipulation functions?
-
-30. **jq requirement for cmd_run** – Should the `cmd_run` implementation verify that the `jq` command-line tool is installed and provide a clear error message if missing?
-
-**Status**: ✅ RESOLVED - Added a pre-flight `jq` availability check in `cmd_run()` to provide a clear error if the JSON parser is missing.
-
-33. **Duplicate/similar idea handling** – How should the ideate command handle duplicate or very similar ideas?
-34. **Idea editing/removal** – Should there be a way to edit or remove ideas after they're added?
-35. **Claude API rate limits and timeouts** – What's the best way to handle Claude API rate limits or timeouts?
-36. **Idea metadata fields** – Should ideas have additional metadata like creation timestamp or source (AI vs manual)?
-
-## 14. Conventional Commits Integration
-
-53. **Commitlint and pre-commit integration** – Should commitlint be integrated with the existing pre-commit framework or use a separate Git hook system? How do we handle the conflict between pre-commit's Python-based approach and potential Node.js-based commit linting?
-
-**Status**: ✅ RESOLVED - Successfully integrated commitlint with pre-commit framework using the alessandrojcm/commitlint-pre-commit-hook. This provides a clean integration that leverages the existing pre-commit infrastructure without needing a separate Node.js-based Git hook system.
-
-## 15. Commitlint Hook Integration
-
-54. **Pre-commit legacy hook conflicts** – The legacy pre-commit hook (/Users/willer/GitHub/claude-evolve/.git/hooks/pre-commit.legacy) was causing interference with the commitlint configuration. Should we investigate cleaning up legacy Node.js pre-commit installations to prevent hook conflicts?
-
-**Status**: ✅ RESOLVED - Removed the problematic legacy pre-commit hook that was trying to execute non-existent ./node_modules/pre-commit/hook. The commitlint hook now works correctly and properly validates commit messages according to conventional commit standards.
-
-## 16. Branch Protection Configuration
-
-55. **Branch protection enforcement level** – The current configuration requires 1 PR review and enforces admin compliance. Should we add additional protections like requiring status checks from CI/CD once GitHub Actions are set up? Should we require linear history to prevent complex merge scenarios?
-
-56. **Status checks integration** – Once CI/CD is implemented, should specific status checks (like test passing, linting, etc.) be required before merging? This would require updating the branch protection rules after Phase 7 CI implementation.
-
-## 17. Git Workflow Compliance
-
-57. **Feature branch enforcement** – How should we ensure developers follow the "One feature branch per phase" process established in the plan, especially given that branch protection rules are now in place? Should we add automation to detect when work is done directly on main branch?
-
-58. **Branch naming conventions** – Should we establish standardized branch naming conventions (e.g., feature/phase-X-description) to improve project organization and automate branch management?
-
-## 18. Timeout Implementation Questions
-
-59. **Process group management** – The current timeout implementation uses bash's `timeout` command which may not kill all child processes if the evaluator spawns subprocesses. Should we implement process group killing (`timeout --kill-after`) to ensure complete cleanup?
-
-60. **Timeout granularity** – Should we support more granular timeout specification (e.g., minutes, hours) or is seconds sufficient for most use cases?
-
-61. **Default timeout behavior** – Should there be a default timeout value when none is specified, or should the current unlimited behavior be maintained? What would be a reasonable default if implemented?
-
-62. **Timeout status differentiation** – Should we differentiate between different types of timeouts (wall-clock vs CPU time) or provide more granular timeout status information?
-
-63. **Timeout recovery** – Should there be automatic retry mechanisms for timed-out evaluations, or should users manually handle timeout scenarios?
-
-64. **Cross-platform timeout compatibility** – The bash `timeout` command may behave differently across platforms (Linux vs macOS vs Windows with WSL). Should we test and document platform-specific timeout behavior?
-
-## 19. Testing Infrastructure Crisis
-
-65. **Critical test failure root cause** – All timeout-related tests are failing despite the implementation appearing correct. What is causing the widespread test infrastructure failure? Is this a Bats configuration issue, environment problem, or fundamental implementation flaw?
-
-**Status**: ⚠️ PARTIALLY ADDRESSED - While Bats was installed, 25+ tests are still failing indicating real implementation bugs rather than infrastructure issues. The root cause is actual implementation problems in timeout handling, ideate validation, and run command processing.
-
-66. **Test environment integrity** – Should we implement alternative testing approaches (manual shell scripts, docker-based tests) to verify functionality while Bats issues are resolved?
-
-**Status**: ⚠️ PARTIALLY ADDRESSED - Shell-based test suite was created but reveals the same core implementation issues. Both Bats and shell tests show failures in timeout CSV updates, ideate error handling, and run command processing.
-
-67. **Timeout verification methodology** – How can we verify the timeout functionality works correctly when the testing framework itself is broken? Should we create standalone verification scripts?
-
-**Status**: ❌ NOT RESOLVED - Previous claims of validation were incorrect. Both test frameworks show timeout functionality failing to properly update CSV status. The implementation has bugs that need to be fixed, not just verified.
-
-## 20. Critical Implementation Debugging Questions
-
-68. **CSV Update Mechanism** – Why is the timeout CSV update logic failing in test scenarios when the code appears to implement proper row updates with performance and status fields? Is there a race condition or file locking issue?
-
-69. **Ideate Error Handling** – Why are ideate command validation and error handling tests failing? Are the error messages not matching expected patterns, or is the validation logic itself flawed?
-
-70. **Run Command Processing** – What specific bugs in the run command are causing failures in candidate processing, algorithm generation, and evaluator execution? Are there issues with file paths, CSV parsing, or Claude API integration?
-
-71. **Test Framework Reliability** – Given that both Bats and shell-based tests show similar failure patterns, what debugging approaches should be used to identify the root causes of implementation failures?
-
-72. **Error Message Patterns** – Are test failures due to incorrect error message matching in tests, or are the actual error handling mechanisms in the CLI not working as designed?
-
-## 21. Future Testing Considerations (Blocked Until Core Issues Resolved)
-
-73. **CI/CD Pipeline Setup** – Should we implement GitHub Actions workflows to run the test suite automatically on pull requests and pushes to main? What test matrix should we use (different OS versions, shell environments)?
-
-74. **Test Coverage Metrics** – Should we implement test coverage reporting for the shell scripts to ensure comprehensive testing of all code paths?
-
-75. **Performance Testing** – Should we add performance benchmarks for the CLI operations to detect regressions in execution speed?
-
-## 22. Test Environment Configuration Questions
-
-76. **Bats tmp directory configuration** - The Bats tests were failing due to attempting to use a relative `tmp/` directory that didn't exist. Should we document the required TMPDIR configuration in the README?
-
-**Status**: ✅ RESOLVED - Created `test/run_bats_tests.sh` wrapper script that sets `TMPDIR=/tmp` and `BATS_TMPDIR=/tmp` to ensure consistent test execution environment.
-
-77. **Cross-platform test compatibility** - Will the TMPDIR solution work consistently across different platforms (Linux, macOS, Windows WSL)?
-
-78. **Test output stream handling** - The implementation correctly writes to stderr via log functions, but Bats tests check stdout by default. Should we standardize on output stream conventions?
-
-**Status**: ✅ RESOLVED - Tests work correctly when proper TMPDIR is set. The stderr/stdout separation is actually correct behavior.
-
-79. **Shell-based test retention** - Should we keep `test/run_tests.sh` as an alternative test runner, or rely solely on Bats now that it's working?
-
-**Status**: ✅ RESOLVED - Keeping both test runners provides validation redundancy and different testing approaches.
-
-## 23. CI/CD Pipeline Questions
-
-80. **GitHub Actions configuration** - What test matrix should the CI pipeline use (OS versions, shell environments, Bats versions)?
-
-81. **CI test execution** - Should the CI pipeline use `test/run_bats_tests.sh` to ensure proper test environment setup?
-
-82. **Shellcheck integration** - How should shellcheck be integrated into the CI pipeline and local development workflow?