Make cache-key required and fix cache restore

- Make cache-key input required to prevent configuration mistakes
- Fix cache key format: use run_id suffix for saves, prefix matching for restores
- Add cache-key to test workflow
- Document cache behavior in README (branch scoping, cross-branch sharing)
- Add CLAUDE.md for Claude Code guidance

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: cosmith

.github/workflows/test.yml

@@ -47,6 +47,7 @@ jobs:
           pattern: 'tests/dummy/*.test.ts'
           total: 3
           index: ${{ matrix.index }}
+          cache-key: integration-tests
 
       - name: Show assigned tests
         run: echo "Worker ${{ matrix.index }} running:${{ steps.split.outputs.tests }}"
@@ -88,6 +89,7 @@ jobs:
         with:
           command: merge
           prefix: 'timing-*/timing-'
+          cache-key: integration-tests
 
       - name: Show saved timings
         run: cat .fairsplice-timings.json

CLAUDE.md

@@ -0,0 +1,57 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Fairsplice is a TypeScript/Bun CLI tool and GitHub Action that optimizes test distribution across parallel workers. It provides CircleCI-style test splitting based on historical timing data for GitHub Actions.
+
+## Commands
+
+```bash
+# Run locally
+bun run index.ts
+
+# Run all tests
+bun test
+
+# Run tests in src directory
+bun test src/
+
+# Run a specific test file
+bun test src/lib/splitFiles.test.ts
+
+# Compile to standalone binary
+bun build ./index.ts --compile --outfile fairsplice
+```
+
+## Architecture
+
+**Entry Point**: `index.ts` - CLI with three commands: `split`, `convert`, `merge`
+
+**Source Structure**:
+- `src/commands/` - CLI command implementations
+  - `split.ts` - Distributes test files across workers using bin packing
+  - `merge.ts` - Aggregates timing JSON files and updates history
+  - `convert.ts` - Converts JUnit XML to timing JSON
+- `src/lib/` - Core algorithms
+  - `splitFiles.ts` - Greedy bin packing algorithm (assigns heaviest tests first to balance workload)
+  - `junit.ts` - JUnit XML parser using `fast-xml-parser`
+  - `average.ts` - Timing averaging utility
+- `src/backend/` - Storage layer
+  - `fileStorage.ts` - JSON-based timing persistence with rolling window of last 10 timings per file
+- `src/config.ts` - Constants (`NUMBER_OF_TIMINGS_TO_KEEP=10`, `DEFAULT_TIMING_IF_MISSING=10000ms`)
+
+**GitHub Action**: `action.yml` - Composite action wrapping the CLI with automatic cache handling
+
+**Data Flow**:
+1. `split` loads cached timings, globs test files, applies bin packing, outputs bucket assignments
+2. Tests run in parallel workers, each outputting JUnit XML
+3. `convert` transforms JUnit XML to timing JSON (one per worker)
+4. `merge` aggregates timing JSONs into cached timings history
+
+## Testing
+
+Tests are co-located with source files (`*.test.ts`). Test fixtures for JUnit parsing are in `src/lib/fixtures/`.
+
+The CI workflow (`.github/workflows/test.yml`) runs unit tests plus a 3-worker integration test that exercises the full split→run→convert→merge pipeline.

README.md

@@ -22,6 +22,7 @@ jobs:
           pattern: 'tests/**/*.py'
           total: 3
           index: ${{ matrix.index }}
+          cache-key: python-tests
 
       - name: Run tests
         run: pytest ${{ steps.split.outputs.tests }} --junit-xml=junit-${{ matrix.index }}.xml
@@ -44,6 +45,7 @@ jobs:
         with:
           command: merge
           prefix: 'junit-*/junit-'
+          cache-key: python-tests
 ```
 
 That's it! Caching is handled automatically.
@@ -116,12 +118,24 @@ That's it! Caching is handled automatically.
 | Input | Required | Description |
 |-------|----------|-------------|
 | `command` | Yes | `split` or `merge` |
+| `cache-key` | Yes | Cache key for storing timings (use different keys for frontend/backend workflows) |
 | `timings-file` | No | JSON file for timings (default: `.fairsplice-timings.json`) |
 | `pattern` | For split | Glob pattern to match test files |
 | `total` | For split | Total number of workers |
 | `index` | For split | Current worker index (0-based) |
 | `prefix` | For merge | Prefix to match JUnit XML files |
 
+### Cache Behavior
+
+Fairsplice uses GitHub Actions cache for storing timing history. Important characteristics:
+
+- **Repository-scoped, branch-gated**: Caches are repository-scoped but restore access is gated by branch context
+- **Default branch is global**: Caches saved from the default branch (usually `main`) are restorable by all branches
+- **Immutable, single-writer**: Each cache key can only be written once; updates require a new key (handled automatically via run ID suffix)
+- **Asymmetric cross-branch sharing**: Restore is permissive (branches can read from main), save is restricted (branches can only write to their own scope)
+
+To seed shared timings for all branches, run the workflow on `main` first. Subsequent PRs and feature branches will restore timings from main's cache.
+
 ### Outputs
 
 | Output | Description |

action.yml

@@ -14,8 +14,7 @@ inputs:
     default: '.fairsplice-timings.json'
   cache-key:
     description: 'Cache key for storing timings (use different keys for frontend/backend workflows)'
-    required: false
-    default: 'default'
+    required: true
   # split inputs
   pattern:
     description: 'Glob pattern to match test files (for split)'
@@ -61,9 +60,8 @@ runs:
       uses: actions/cache/restore@v4
       with:
         path: ${{ inputs.timings-file }}
-        key: fairsplice-${{ inputs.cache-key }}-${{ github.repository }}
-        restore-keys: |
-          fairsplice-${{ inputs.cache-key }}-${{ github.repository }}
+        key: fairsplice-${{ inputs.cache-key }}-${{ github.repository }}-${{ github.run_id }}
+        restore-keys: fairsplice-${{ inputs.cache-key }}-${{ github.repository }}-
 
     - name: Run split
       id: split