feat(publish-ready): argparse hardening, docs overhaul, QOL improvements

Batch 1 — Critical Path:
- Move --evaluator-command to last flag position (nargs="+" greedy fix)
- Add runtime validation detecting flag-like tokens in evaluator command
- Add zero-proposals detection (error on 0, warning on 1 candidate)
- Update CLAUDE.md: new commands, delivery surfaces, Known Gotchas
- Update AGENTS.md: optimization workflow, file organization sections

Batch 2 — Documentation:
- Create CONCEPTS.md glossary (12 core concept entries)
- Create WALKTHROUGH.md tutorial (9-step optimization guide)
- Update README.md: --model, --judge-model, --spec-file, --run-dir,
  --diff flags; score subcommand section; architecture entries
- Add pyproject.toml packaging metadata (license, classifiers, URLs)

Batch 3 — QOL + Testing:
- Add Makefile with 9 common dev targets
- Add pytest addopts, testpaths, filterwarnings to pyproject.toml
- CI: exclude integration tests from default test job
- 8 new tests: argparse ordering (3), zero-proposals (1),
  code fence variants (2), RED all-None (1), baseline 0.0 (1)

215 tests passing.

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

Author: ASRagab

.github/workflows/ci.yml

@@ -31,8 +31,8 @@ jobs:
       - name: Install dependencies
         run: uv sync
 
-      - name: Run pytest
-        run: uv run pytest -v
+      - name: Run pytest (excluding integration)
+        run: uv run pytest -v -m "not integration"
 
       - name: Smoke harness (budget=1)
         run: uv run python scripts/smoke_harness.py --budget 1

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 Core code lives in `src/optimize_anything/`:
-- `cli.py` for `optimize-anything` subcommands (`optimize`, `generate-evaluator`, `intake`, `explain`, `budget`)
+- `cli.py` for `optimize-anything` subcommands (`optimize`, `generate-evaluator`, `intake`, `explain`, `budget`, `score`)
 - `evaluators.py` for command/HTTP evaluator adapters
 - `intake.py` for intake schema normalization (`evaluation_pattern`, `execution_mode`, `quality_dimensions`, constraints)
 - `evaluator_generator.py` for evaluator scaffolding from seed/objective/intake
@@ -43,3 +43,24 @@ For PRs, include:
 - linked issue (if any),
 - test evidence (command + result),
 - sample CLI output when behavior changes.
+
+## Optimization Workflow
+
+When running RED-GREEN-OBSERVER cycles:
+1. Always pass `--model` explicitly to `live_integration.py`
+2. Place `--evaluator-command` as the LAST flag
+3. Run RED validation after every GREEN improvement
+4. Accept artifacts only when cross_provider_delta < 0.2
+5. Update baselines with `score_check.py --update` after accepting
+6. Commit with descriptive message including score deltas
+
+## File Organization
+
+- `src/optimize_anything/` — package source (all Python modules)
+- `scripts/` — operational scripts (gates, smoke, live integration)
+- `skills/` — optimizable skill artifacts (SKILL.md files)
+- `evaluators/` — production evaluator scripts
+- `examples/` — sample evaluators and seeds
+- `tests/` — pytest test suite
+- `docs/` — planning and handoff documents (gitignored from commits)
+- `integration_runs/` — optimization run artifacts (gitignored)

CLAUDE.md

@@ -11,11 +11,21 @@ uv run pytest tests/test_cli.py                   # Run one test module
 uv run pytest -k "optimize"                       # Run tests by pattern
 uv run optimize-anything --help                   # CLI entry point
 uv run optimize-anything score FILE --evaluator-command bash eval.sh  # Score one artifact
+uv run optimize-anything score FILE --judge-model openai/gpt-4o-mini --objective "Score clarity"  # LLM judge scoring
 uv run python scripts/check.py                    # Unified gate: pytest + smoke + score_check
 uv run python scripts/check.py --skip-smoke       # Unified gate without smoke (offline)
 uv run python scripts/smoke_harness.py --budget 1 # CLI smoke check
 uv run python scripts/score_check.py              # Score regression check
 uv run python scripts/score_check.py --update     # Update baselines after improvement
+uv run python scripts/live_integration.py --phase green \
+    --artifact FILE --model openai/gpt-4o-mini --budget 15 \
+    --objective "..." --run-dir integration_runs \
+    --evaluator-command bash evaluators/skill_clarity.sh  # GREEN phase optimization
+uv run python scripts/live_integration.py --phase red \
+    --artifact FILE --objective "..." \
+    --providers openai/gpt-5.1-mini anthropic/claude-sonnet-4-5-20250929 \
+    --baseline 0.85 \
+    --evaluator-command bash evaluators/skill_clarity.sh  # RED phase validation
 ```
 
 ## Architecture
@@ -66,6 +76,17 @@ Input/output contract for external evaluators:
 - `src/optimize_anything/result_contract.py`
   - Canonical optimize summary for CLI output
 
+- `src/optimize_anything/spec_loader.py`
+  - TOML spec file loading for repeatable optimization runs
+  - `--spec-file` flag overrides CLI arguments with spec values
+
+- `scripts/live_integration.py`
+  - RED-GREEN-OBSERVER cycle orchestrator
+  - `--phase green`: optimize artifact, output structured JSON
+  - `--phase red`: multi-provider scoring, output score matrix
+  - `--model`: proposer LLM (REQUIRED — gepa default may be unavailable)
+  - `--evaluator-command` MUST be the last flag (nargs="+" greedy parsing)
+
 ## Important Distinction
 
 - `execution_mode` / runtime type: transport and execution path (`command` vs `http`)
@@ -88,8 +109,20 @@ skills/optimization-guide/
 - CLI tests call `main(argv)`.
 - Evaluator tests include command, HTTP, timeout, and malformed payload cases.
 - LLM judge unit tests mock `litellm.completion`; integration tests skip via `@pytest.mark.skipif` when API keys absent.
+- Live integration tests in `tests/test_live_integration.py`.
+- `@pytest.mark.integration` for tests requiring API keys.
+- Code fence stripping tested in `test_llm_judge.py`.
 - Doc drift checks live in `tests/test_doc_contract.py`.
 
+## Known Gotchas
+
+- `--evaluator-command` in `live_integration.py` uses `nargs="+"` — must be the LAST
+  flag or it swallows subsequent arguments like `--model`
+- gepa's default proposer model may be unavailable — always pass `--model` explicitly
+- Anthropic models wrap JSON responses in markdown code fences — `llm_judge.py`
+  strips these automatically
+- `scores.json` baselines: use `score_check.py --update` after accepting improvements
+
 ## Dependencies
 
 - `gepa` (optimization engine)

CONCEPTS.md

@@ -0,0 +1,64 @@
+# Concepts
+
+Core concepts for understanding optimize-anything. For a hands-on tutorial, see [WALKTHROUGH.md](WALKTHROUGH.md).
+
+## Artifact
+
+The text being optimized. Can be a prompt, config, skill file, evaluator script, or any text where quality can be scored. Passed as a file path to the CLI.
+
+## Evaluator
+
+A function that scores an artifact candidate. Returns `{"score": <float>, ...}`. Three runtime modes:
+
+- **Command** (`--evaluator-command`): shell script receiving JSON on stdin
+- **HTTP** (`--evaluator-url`): endpoint receiving POST JSON
+- **LLM judge** (`--judge-model`): litellm-backed model scoring against an objective
+
+## Evaluator Protocol
+
+- **Input:** `{"candidate": "<text>"}` via stdin (command) or POST body (HTTP)
+- **Output:** JSON with required `score` key (0.0-1.0) and optional diagnostic keys
+- Diagnostic keys become "Actionable Side Information" for gepa's reflection LM
+
+## Evaluation Pattern vs Execution Mode
+
+Two independent axes:
+
+| Concept | What it answers | Values |
+|---------|----------------|--------|
+| `execution_mode` | How the evaluator runs (transport) | `command`, `http` |
+| `evaluation_pattern` | What scoring strategy it implements (intent) | `verification`, `judge`, `simulation`, `composite` |
+
+A verification evaluator can run as a command or HTTP endpoint. These are never conflated.
+
+## gepa
+
+The optimization engine. Runs propose/evaluate/reflect cycles to improve artifacts. Uses a proposer LLM to generate candidates and an evaluator to score them. Configure with `--model` (proposer) and `--budget` (max evaluator calls).
+
+## Intake Specification
+
+Schema describing what the evaluator expects: quality dimensions (with weights), hard constraints, evaluation pattern, and execution mode. Normalized by `intake.py`. Provide via `--intake-json` or `--intake-file`.
+
+## Quality Dimensions
+
+Named scoring axes (e.g., "clarity", "conciseness") with float weights that sum to 1.0. Used by the LLM judge for dimension-weighted scoring and by intake normalization.
+
+## Hard Constraints
+
+Boolean pass/fail conditions. If any constraint is violated, the LLM judge forces the score to 0.0 regardless of other dimensions.
+
+## RED-GREEN-OBSERVER Cycle
+
+An iterative optimization workflow orchestrated by `scripts/live_integration.py`:
+
+- **GREEN:** Run gepa to optimize an artifact (proposer generates, evaluator scores)
+- **RED:** Validate the result with multi-provider scoring (command + LLM judges)
+- **OBSERVER:** Read the score matrix and decide: continue, adjust objective, or stop
+
+## Score Baselines
+
+Tracked in `scores.json`. The `score_check.py` script ensures artifacts don't regress below their baselines. Use `--update` to raise baselines after improvements.
+
+## Spec File
+
+A TOML file (`--spec-file`) that bundles optimization parameters (artifact path, evaluator, budget, objective) for repeatable runs. Loaded by `spec_loader.py`.

Makefile

@@ -0,0 +1,29 @@
+.PHONY: test test-fast gates gates-offline smoke score-check score-update install help
+
+test:                     ## Run full test suite
+	uv run pytest -v
+
+test-fast:                ## Run tests excluding integration
+	uv run pytest -v -m "not integration"
+
+gates:                    ## Run all quality gates
+	uv run python scripts/check.py
+
+gates-offline:            ## Run gates without smoke (no API calls)
+	uv run python scripts/check.py --skip-smoke
+
+smoke:                    ## Run smoke harness
+	uv run python scripts/smoke_harness.py --budget 1
+
+score-check:              ## Check score baselines
+	uv run python scripts/score_check.py
+
+score-update:             ## Update score baselines
+	uv run python scripts/score_check.py --update
+
+install:                  ## Install dependencies
+	uv sync
+
+help:                     ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
+	  awk 'BEGIN {FS = ":.*?## "}; {printf "  %-18s %s\n", $$1, $$2}'

README.md

@@ -199,11 +199,19 @@ uv run optimize-anything optimize <seed_file> [options]
 | `--objective <text>` | Natural language objective | -- |
 | `--background <text>` | Domain knowledge/constraints | -- |
 | `--budget <n>` | Max evaluator invocations | 100 |
+| `--model <model>` | Proposer LLM (e.g., `openai/gpt-4o-mini`) | env `OPTIMIZE_ANYTHING_MODEL` |
+| `--judge-model <model>` | LLM judge evaluator (mutually exclusive with `--evaluator-command`/`--evaluator-url`) | -- |
+| `--judge-objective <text>` | Override objective for the judge (falls back to `--objective`) | -- |
+| `--spec-file <path>` | TOML spec file with bundled optimization parameters | -- |
+| `--run-dir <path>` | Directory to save run artifacts (auto-timestamped subdirectory) | -- |
+| `--diff` | Show diff between seed and best candidate on stderr | -- |
 | `--output, -o <file>` | Write best candidate to file | stdout |
 
 If intake is provided, `execution_mode` is used to decide which evaluator source flag is required when neither `--evaluator-command` nor `--evaluator-url` is set. Explicit evaluator flags always win if both explicit flags and intake are supplied.
 `--output` must be a file path (not an existing directory).
 
+> **Note:** Always pass `--model` explicitly when using gepa — the default proposer model may be unavailable in your environment.
+
 ### explain
 
 ```bash
@@ -254,6 +262,34 @@ Normalize and validate an evaluator intake specification. Outputs canonical JSON
 | `--intake-json <json>` | Inline intake spec JSON (mutually exclusive with flags) | -- |
 | `--intake-file <path>` | Path to intake spec JSON file (mutually exclusive with flags) | -- |
 
+### score
+
+Score a single artifact without running optimization:
+
+```bash
+# With command evaluator
+uv run optimize-anything score artifact.txt \
+    --evaluator-command bash evaluators/eval.sh
+
+# With LLM judge
+uv run optimize-anything score artifact.txt \
+    --judge-model openai/gpt-4o-mini \
+    --objective "Score clarity, actionability, and specificity"
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `artifact_file` | Path to artifact to score | (required) |
+| `--evaluator-command <cmd...>` | Shell command evaluator | -- |
+| `--evaluator-url <url>` | HTTP POST evaluator URL | -- |
+| `--judge-model <model>` | LLM judge model | -- |
+| `--objective <text>` | Objective for LLM judge scoring | -- |
+| `--judge-objective <text>` | Override objective for the judge | -- |
+| `--intake-json <json>` | Inline intake spec JSON | -- |
+| `--intake-file <path>` | Path to intake spec JSON file | -- |
+
+Exactly one of `--evaluator-command`, `--evaluator-url`, or `--judge-model` is required.
+
 ## Architecture
 
 ```
@@ -263,6 +299,8 @@ src/optimize_anything/
   evaluator_generator.py   # Generate evaluator scripts from seed + objective
   cli.py                   # CLI entry point (argparse)
   intake.py                # Intake schema normalization
+  llm_judge.py             # LLM-as-judge evaluator (litellm)
+  spec_loader.py           # TOML spec file loading
   result_contract.py       # Canonical optimize summary output
   __main__.py              # python -m support
 
@@ -339,8 +377,10 @@ uv tool uninstall optimize-anything
 claude plugin remove optimize-anything
 ```
 
-## Links
+## Learn More
 
+- [Concepts](CONCEPTS.md) — glossary of core terms and architecture
+- [Walkthrough](WALKTHROUGH.md) — step-by-step tutorial for a full optimization cycle
 - [Installation Guide](install.md)
 - [Evaluator Cookbook](evaluator-cookbook.md)
 - [Examples](examples/)