claude-turing 2.0.0 → 2.2.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "turing",
-  "version": "2.0.0",
-  "description": "Autonomous ML research harness — the autoresearch loop as a formal protocol. 25 commands, 2 specialized agents, production model export (6 formats, equivalence verification, latency benchmarking), performance profiling, smart Pareto-based checkpoint management, experiment intelligence (error analysis, ablation studies, Pareto frontiers), statistical rigor (multi-seed studies, reproducibility verification), tree-search hypothesis exploration (TreeQuest AB-MCTS), cost-performance frontier analysis, model cards, model registry, hypothesis database with novelty guard, anti-cheating guardrails, and the taste-leverage loop. Inspired by Karpathy's autoresearch and the scientific method itself.",
+  "version": "2.2.0",
+  "description": "Autonomous ML research harness — the autoresearch loop as a formal protocol. 30 commands, 2 specialized agents, experiment orchestration (batch queue + smart retry + branching), literature integration + paper drafting, production model export, performance profiling, smart checkpoints, experiment intelligence, statistical rigor, tree-search hypothesis exploration, cost-performance frontier, model cards, model registry, hypothesis database with novelty guard, anti-cheating guardrails, and the taste-leverage loop. Inspired by Karpathy's autoresearch and the scientific method itself.",
   "author": {
     "name": "pragnition"
   },

package/README.md

@@ -330,6 +330,11 @@ The index (`hypotheses.yaml`) is the lightweight queue. The detail files (`hypot
 | `/turing:frontier [--metrics]` | Pareto frontier — multi-objective tradeoff visualization |
 | `/turing:profile [exp-id]` | Computational profiling — timing, memory, throughput, bottleneck detection |
 | `/turing:checkpoint <action>` | Smart checkpoint management — list, prune (Pareto), average, resume, stats |
+| `/turing:lit <query>` | Literature search — papers, SOTA baselines, related work |
+| `/turing:paper [--sections] [--format]` | Draft paper sections from experiment logs (setup, results, ablation, hyperparams) |
+| `/turing:queue <action>` | Batch experiment scheduler — add, list, run, pause, clear |
+| `/turing:retry <exp-id>` | Smart failure recovery — auto-diagnose crash, apply fix, re-run |
+| `/turing:fork <exp-id>` | Experiment branching — run parallel tracks, report winner |
 | `/turing:export [--format]` | Export model to production format with equivalence check + latency benchmark |
 | `/turing:card` | Generate a model card — performance, limitations, intended use, artifact contract |
 | `/turing:logbook` | Generate HTML experiment logbook |
@@ -520,11 +525,11 @@ Each project gets independent config, data, experiments, models, and agent memor
 
 ## Architecture of Turing Itself
 
-25 commands, 2 agents, 8 config files, 44 template scripts, model registry, artifact contract, cost-performance frontier, model cards, tree-search exploration, statistical rigor, experiment intelligence, performance profiling, smart checkpoints, production model export, 611 tests, 16 ADRs. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full codemap.
+30 commands, 2 agents, 9 config files, 49 template scripts, model registry, artifact contract, cost-performance frontier, model cards, tree-search exploration, statistical rigor, experiment intelligence, performance profiling, smart checkpoints, production model export, literature integration, paper section drafting, experiment orchestration (queue + retry + fork), 727 tests, 16 ADRs. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full codemap.
 
 ```
 turing/
-├── commands/              24 skill files (core + taste-leverage + reporting + exploration + statistical rigor + experiment intelligence + performance + deployment)
+├── commands/              29 skill files (core + taste-leverage + reporting + exploration + statistical rigor + experiment intelligence + performance + deployment + research workflow + orchestration)
 ├── agents/                2 agents (researcher: read/write, evaluator: read-only)
 ├── config/                8 files (lifecycle, taxonomy, archetypes, novelty aliases)
 ├── templates/             Scaffolded into user projects by /turing:init

package/commands/fork.md

@@ -0,0 +1,40 @@
+---
+name: fork
+description: Branch an experiment into parallel tracks — run both A and B, report the winner.
+disable-model-invocation: true
+argument-hint: "<exp-id> --branches \"approach A\" \"approach B\" [--auto-promote]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Fork an experiment into parallel branches and compare results.
+
+## Steps
+
+1. **Activate environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+2. **Parse arguments from `$ARGUMENTS`:**
+   - First argument is the parent experiment ID
+   - `--branches "A" "B" "C"` — branch descriptions (2+ required)
+   - `--auto-promote` — automatically keep the winning branch
+
+3. **Run fork:**
+   ```bash
+   python scripts/fork_experiment.py $ARGUMENTS
+   ```
+
+4. **Report results:**
+   - Comparison tree showing each branch's metric
+   - Winner identified and marked
+   - Recommendation: promote winner, abandon rest
+
+5. **Saved output:** report written to `experiments/forks/exp-NNN-fork.yaml`
+
+## Examples
+
+```
+/turing:fork exp-042 --branches "LightGBM with dart" "XGBoost deeper trees"
+/turing:fork exp-042 --branches "A" "B" "C" --auto-promote
+```

package/commands/lit.md

@@ -0,0 +1,47 @@
+---
+name: lit
+description: Literature search scoped to the current experiment domain — find papers, SOTA baselines, and related work without leaving the terminal.
+disable-model-invocation: true
+argument-hint: "<query> | --baseline | --related <exp-id>"
+allowed-tools: Read, Bash(*), Grep, Glob, WebSearch
+---
+
+Search the literature for papers, baselines, and related work.
+
+## Steps
+
+1. **Activate environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+2. **Parse arguments from `$ARGUMENTS`:**
+   - **Free query:** `"gradient boosting for tabular data"` — searches Semantic Scholar
+   - **Baseline:** `--baseline` — finds SOTA results for the current task, compares against your best
+   - **Related:** `--related exp-042` — finds papers using similar methods to a specific experiment
+   - `--auto-queue` — auto-queues hypotheses from literature with `source: "literature"`
+   - `--limit 10` — max number of results
+
+3. **Run literature search:**
+   ```bash
+   python scripts/literature_search.py $ARGUMENTS
+   ```
+
+4. **Report results:**
+   - **Papers:** title, authors, year, venue, citations, abstract snippet, URL
+   - **Baseline mode:** SOTA comparison with gap analysis against current best
+   - **Related mode:** methodological differences worth investigating
+   - **Hypotheses:** if `--auto-queue`, shows queued experiments from findings
+
+5. **Saved output:** results written to `experiments/literature/query-YYYY-MM-DD-HHMMSS.md`
+
+6. **If API unavailable:** reports error and suggests manual search.
+
+## Examples
+
+```
+/turing:lit "gradient boosting missing values"    # Free query
+/turing:lit --baseline                             # SOTA comparison
+/turing:lit --related exp-042                      # Related work
+/turing:lit --auto-queue "ensemble methods"        # Queue hypotheses
+```

package/commands/paper.md

@@ -0,0 +1,44 @@
+---
+name: paper
+description: Draft mechanical paper sections (setup, results, ablation, hyperparameters) from experiment logs. LaTeX and markdown output.
+disable-model-invocation: true
+argument-hint: "[--sections setup,results,ablation] [--format latex|markdown]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Draft paper sections directly from experiment data.
+
+## Steps
+
+1. **Activate environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+2. **Parse arguments from `$ARGUMENTS`:**
+   - `--sections setup,results,ablation,hyperparameters` — which sections to draft (default: all)
+   - `--format latex|markdown` — output format (default: latex)
+
+3. **Run paper drafting:**
+   ```bash
+   python scripts/draft_paper_sections.py $ARGUMENTS
+   ```
+
+4. **Report results:**
+   - **setup:** Experimental setup prose (dataset, metrics, split, seed methodology)
+   - **results:** Comparison table with all model types, best bolded, seed study stats
+   - **ablation:** Ablation table from `/turing:ablate` results
+   - **hyperparameters:** Appendix-style parameter table per model
+
+5. **Output:** Each section saved to `paper/sections/` as `.tex` or `.md`
+
+6. **Numbers are pulled directly from experiment logs** — no manual transcription needed.
+
+## Examples
+
+```
+/turing:paper                                        # All sections, LaTeX
+/turing:paper --format markdown                      # All sections, markdown
+/turing:paper --sections setup,results               # Just setup + results
+/turing:paper --sections ablation --format latex      # Just ablation table
+```

package/commands/queue.md

@@ -0,0 +1,48 @@
+---
+name: queue
+description: Queue experiments for batch execution with priority ordering and dependency chains. Load the queue, walk away, read the summary.
+disable-model-invocation: true
+argument-hint: "<add|list|run|pause|clear> [description] [--priority high] [--after q-001]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Manage the experiment queue for unattended batch execution.
+
+## Steps
+
+1. **Activate environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+2. **Parse arguments from `$ARGUMENTS`:**
+   - **add** `"description"` `--priority high` `--after q-001` — queue an experiment
+   - **list** — show queue with status, priority, dependencies
+   - **run** `--halt-on-error` — execute all queued experiments
+   - **pause** — stop after current experiment finishes
+   - **clear** — discard all queued items
+
+3. **Run queue manager:**
+   ```bash
+   python scripts/experiment_queue.py $ARGUMENTS
+   ```
+
+4. **Report results by action:**
+   - **add:** confirms ID and priority
+   - **list:** table of queued/completed/failed items
+   - **run:** batch summary with per-experiment status
+   - **pause/clear:** confirmation message
+
+5. **Queue persists in** `experiments/queue.yaml`
+
+## Examples
+
+```
+/turing:queue add "try LightGBM" --priority high
+/turing:queue add "deeper trees" --after q-001
+/turing:queue list
+/turing:queue run
+/turing:queue run --halt-on-error
+/turing:queue pause
+/turing:queue clear
+```

package/commands/retry.md

@@ -0,0 +1,41 @@
+---
+name: retry
+description: Smart failure recovery — auto-diagnose crash type and retry with targeted fix. OOM → halve batch. NaN → add clipping.
+disable-model-invocation: true
+argument-hint: "<exp-id> [--max-attempts 3]"
+allowed-tools: Read, Bash(*), Grep, Glob
+---
+
+Auto-diagnose and recover from experiment failures.
+
+## Steps
+
+1. **Activate environment:**
+   ```bash
+   source .venv/bin/activate
+   ```
+
+2. **Parse arguments from `$ARGUMENTS`:**
+   - First argument is the experiment ID (required)
+   - `--max-attempts 3` limits retry count
+   - `--classify "error text"` just classifies without retrying
+
+3. **Run smart retry:**
+   ```bash
+   python scripts/smart_retry.py $ARGUMENTS
+   ```
+
+4. **Report results:**
+   - **RECOVERED:** fix applied, retry succeeded
+   - **FAILED:** all retry attempts exhausted
+   - **MANUAL FIX NEEDED:** failure type requires human intervention
+   - Shows failure classification, fix applied, and attempt history
+
+5. **Saved output:** report written to `experiments/retries/exp-NNN-retry.yaml`
+
+## Examples
+
+```
+/turing:retry exp-042                    # Auto-diagnose and retry
+/turing:retry exp-042 --max-attempts 5   # More retries
+```

package/commands/turing.md

@@ -31,7 +31,12 @@ You are the Turing ML research router. Detect the user's intent and route to the
 | "diagnose", "error analysis", "failure modes", "where does it fail", "confusion matrix" | `/turing:diagnose` | Analyze |
 | "ablate", "ablation", "remove component", "which features matter", "component impact" | `/turing:ablate` | Analyze |
 | "frontier", "pareto", "tradeoff", "tradeoffs", "multi-objective", "which model is best" | `/turing:frontier` | Analyze |
+| "lit", "literature", "papers", "SOTA", "baseline", "related work", "citations" | `/turing:lit` | Research |
+| "paper", "draft paper", "write paper", "results table", "latex", "experimental setup" | `/turing:paper` | Document |
 | "export", "deploy", "production", "onnx", "torchscript", "tflite", "ship model" | `/turing:export` | Deploy |
+| "queue", "batch", "overnight", "schedule experiments", "run queue" | `/turing:queue` | Orchestrate |
+| "retry", "retry experiment", "crashed", "OOM", "fix and rerun" | `/turing:retry` | Orchestrate |
+| "fork", "branch", "try both", "parallel experiments", "A or B" | `/turing:fork` | Orchestrate |
 | "profile", "profiling", "bottleneck", "slow training", "why is it slow", "timing" | `/turing:profile` | Check |
 | "checkpoint", "checkpoints", "prune checkpoints", "disk space", "resume training" | `/turing:checkpoint` | Check |
 
@@ -61,7 +66,12 @@ You are the Turing ML research router. Detect the user's intent and route to the
 | `/turing:diagnose [exp-id]` | Error analysis: failure modes, confused pairs, feature-range bias | (inline) |
 | `/turing:ablate [--components]` | Ablation study: remove components, measure impact, flag dead weight | (inline) |
 | `/turing:frontier [--metrics]` | Pareto frontier: multi-objective tradeoff visualization | (inline) |
+| `/turing:lit <query>` | Literature search: papers, SOTA baselines, related work | (inline, uses WebSearch) |
+| `/turing:paper [--sections] [--format]` | Draft paper sections from experiment logs (setup, results, ablation, hyperparams) | (inline) |
 | `/turing:export [exp-id] [--format]` | Export model to production format with equivalence check + latency benchmark | (inline) |
+| `/turing:queue <action>` | Batch experiment scheduler: add, list, run, pause, clear | (inline) |
+| `/turing:retry <exp-id>` | Smart failure recovery: auto-diagnose crash, apply fix, re-run | (inline) |
+| `/turing:fork <exp-id> --branches` | Experiment branching: run parallel tracks, report winner | (inline) |
 | `/turing:profile [exp-id]` | Computational profiling: timing, memory, throughput, bottleneck detection | (inline) |
 | `/turing:checkpoint <action>` | Smart checkpoint management: list, prune (Pareto), average, resume, stats | (inline) |
 

package/config/failure_modes.yaml

@@ -0,0 +1,74 @@
+# Configurable failure taxonomy for /turing:retry
+# Add project-specific patterns to extend the built-in taxonomy.
+# Each failure mode has:
+#   patterns: list of strings to match in stdout/stderr (case-insensitive)
+#   fix: human-readable description of the fix
+#   config_changes: dict of hyperparameter changes (//N = divide, *N = multiply)
+#   severity: recoverable | requires_intervention
+
+oom:
+  patterns:
+    - "CUDA out of memory"
+    - "MemoryError"
+    - "RuntimeError: out of memory"
+    - "std::bad_alloc"
+    - "OutOfMemoryError"
+  fix: "Reduce batch_size by 50%"
+  config_changes:
+    batch_size: "//2"
+  severity: recoverable
+
+nan_loss:
+  patterns:
+    - "loss is NaN"
+    - "loss is nan"
+    - "RuntimeWarning: invalid value"
+    - "loss: nan"
+    - "NaN loss"
+  fix: "Add gradient clipping at 1.0, reduce learning_rate by 10x"
+  config_changes:
+    gradient_clip: 1.0
+    learning_rate: "//10"
+  severity: recoverable
+
+timeout:
+  patterns:
+    - "TimeoutError"
+    - "exceeded time limit"
+    - "timed out"
+    - "TimeoutExpired"
+  fix: "Double max_epochs or training timeout"
+  config_changes:
+    max_epochs: "*2"
+  severity: recoverable
+
+import_error:
+  patterns:
+    - "ModuleNotFoundError"
+    - "ImportError"
+    - "No module named"
+  fix: "Install missing dependency"
+  config_changes: {}
+  severity: requires_intervention
+
+convergence_failure:
+  patterns:
+    - "loss did not decrease"
+    - "no improvement"
+    - "early stopping"
+    - "convergence warning"
+  fix: "Increase learning_rate by 3x for warm-up"
+  config_changes:
+    learning_rate: "*3"
+  severity: recoverable
+
+data_error:
+  patterns:
+    - "FileNotFoundError"
+    - "No such file"
+    - "empty dataset"
+    - "zero samples"
+    - "KeyError"
+  fix: "Check data path and preprocessing"
+  config_changes: {}
+  severity: requires_intervention

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-turing",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "type": "module",
   "description": "Autonomous ML research harness for Claude Code. The autoresearch loop as a formal protocol — iteratively trains, evaluates, and improves ML models with structured experiment tracking, convergence detection, immutable evaluation infrastructure, and safety guardrails.",
   "bin": {

package/src/install.js

@@ -24,6 +24,7 @@ const SUB_COMMANDS = [
   "try", "brief", "suggest", "explore", "design", "logbook", "poster",
   "report", "mode", "preflight", "card", "seed", "reproduce",
   "diagnose", "ablate", "frontier", "profile", "checkpoint", "export",
+  "lit", "paper", "queue", "retry", "fork",
 ];
 
 export async function install(opts = {}) {
@@ -77,6 +78,7 @@ export async function install(opts = {}) {
     "defaults.yaml", "lifecycle.toml", "taxonomy.toml",
     "experiment_archetypes.yaml", "novelty_aliases.yaml",
     "relationships.toml", "state.toml", "task_taxonomy.yaml",
+    "failure_modes.yaml",
   ];
   for (const file of CONFIG_FILES) {
     await copyFile(

package/src/verify.js

@@ -39,6 +39,11 @@ const EXPECTED_COMMANDS = [
   "profile/SKILL.md",
   "checkpoint/SKILL.md",
   "export/SKILL.md",
+  "lit/SKILL.md",
+  "paper/SKILL.md",
+  "queue/SKILL.md",
+  "retry/SKILL.md",
+  "fork/SKILL.md",
 ];
 
 const EXPECTED_AGENTS = ["ml-researcher.md", "ml-evaluator.md"];
@@ -47,6 +52,7 @@ const EXPECTED_CONFIG = [
   "defaults.yaml", "lifecycle.toml", "taxonomy.toml",
   "experiment_archetypes.yaml", "novelty_aliases.yaml",
   "relationships.toml", "state.toml", "task_taxonomy.yaml",
+  "failure_modes.yaml",
 ];
 
 async function fileExists(path) {