/run

name: run
description: Sustained metric-improvement loop with atomic commits, auto-rollback, and experiment logging. Iterates with specialist agents, commits atomically, auto-rolls back on regression. Accepts a program.md file path. Supports --resume, --team, --colab, --codex, --researcher, --architect, --journal, --hypothesis.
argument-hint: <program.md> [clarification] [--resume <program.md>] [--team] [--compute=local|colab|docker] [--colab[=H100|L4|T4|A100]] [--codex] [--researcher] [--architect] [--journal] [--hypothesis <path>] [--scientist] [--codemap] [--no-codemap] [--keep "<items>"]
effort: xhigh
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, TaskCreate, TaskUpdate, AskUserQuestion, Skill
disable-model-invocation: true

<objective>

Sustained metric-improvement loop — reads `program.md`, iterates specialist ideation agents, commits atomically, auto-rolls back on regression. For long-running automated improvement campaigns.

NOT for: methodology validation before run (use `/research:judge`); hypothesis generation (use `research:scientist` agent); one-off feature work (use `/develop:feature`); no `program.md` yet / starting from a bare goal (use `/research:sweep`).

Accept a metric-improvement campaign on a `program.md`, including a dry-run/walkthrough of that campaign (trace only; execute nothing). A bare goal → redirect to `/research:sweep` to build and judge the program first. Any other request → print `! UNSUPPORTED — /research:run cannot do this request`, name the redirect, stop. Never perform the out-of-scope task after the redirect — no "direct answer" section, no partial findings.

</objective>

<constants>

Campaign mode only:

MAX_ITERATIONS:             50 (hard cap); DEFAULT 20 when max_iterations unset in program.md; program.md may raise up to 50; values above 50 clamped to 50 with a warning
MAX_CODEX_RUNS:             10 (cost ceiling for --codex Phase 2c — disable Codex once exceeded)
STUCK_THRESHOLD:            5 consecutive discards → escalation
GUARD_REWORK_MAX:           2 attempts before revert
VERIFY_TIMEOUT_SEC:         120 (local), 300 (--colab)
COLAB_KNOWN_HW:             H100, L4, T4, A100
SUMMARY_INTERVAL:           10 iterations
DIMINISHING_RETURNS_WINDOW: 5 iterations < 0.5% each → warn user and suggest stopping
STATE_DIR:                  .experiments/state/<run-id>/  (timestamped dir per run — foundry artifact-lifecycle rule, requires foundry plugin)
METRIC_REPEATS_DEFAULT:     1 (metric runs per measurement; ## Config metric_repeats 1–10 overrides; 1 = single sample, keep any measured gain)
MIN_DELTA_PCT:              0.1 (% of |best_metric|; ## Config min_delta_pct overrides — smallest gain kept when metric_repeats > 1, and the tiny-gain-on-large-change discard threshold)

**Repeated measurement** (`metric_repeats` > 1 — opt-in, each iteration's metric cost × `metric_repeats`): R4 and Phase 5 run `metric_cmd` that many times, each run its own Bash/MCP call under its own `VERIFY_TIMEOUT_MS`, each staged as one line of `STATE_DIR/metric-runs.jsonl`; `bin/run_metric_stats.py status` is the cursor and `decide` is Phase 7's verdict — keep only a gain beyond `max(min_delta_pct, 2σΔ)`, the noise model `/research:fortify` ranks ablations with. Recorded metric = mean of the runs; scalar `metric` fields keep their meaning for every reader.

<!-- Note: STATE_DIR (.experiments/state/) holds per-iteration artifacts (diary, experiments.jsonl). Hypothesis pipeline outputs (hypotheses.jsonl, checkpoint.jsonl, journal.md) go to .experiments/<run-id>/ (RUN_DIR). These are two separate directories by design — see protocol.md for layout. -->

<!-- policy-sibling: plugins/cc_research/skills/run/modes/colab-setup.md, plugins/cc_research/skills/plan/SKILL.md, plugins/cc_research/skills/sweep/SKILL.md, plugins/cc_research/skills/judge/SKILL.md — COLAB_KNOWN_HW set restated in each; keep in sync (plugins/CLAUDE.md §Policy Duplication Marker). -->

**Agent strategy mapping** (`agent_strategy` in config → ideation agent to spawn):

| `agent_strategy` | Specialist agent | When to use | | -- | -- | -- | | `auto` | heuristic | Default — infer from metric_cmd keywords | | `perf` | `foundry:perf-optimizer` | latency, throughput, memory, GPU utilization | | `code` | `foundry:sw-engineer` | coverage, complexity, lines, coupling | | `ml` | `research:scientist` proposes, `foundry:sw-engineer` implements (Phase 2) | accuracy, loss, F1, AUC, BLEU | | `arch` | `foundry:solution-architect` proposes, `foundry:sw-engineer` implements (Phase 2) | coupling, cohesion, modularity metrics |

**Auto-inference keyword heuristics** (when `agent_strategy: auto` or omitted; checked against `## Goal` text AND metric command):

**Precedence order** (first match wins; ML keywords beat test-framework keywords). ML-specific compound terms (not bare tokens) required — prevents over-triggering on `eval`/`train`/`val` as common words:

• contains `accuracy`, `loss` (paired with `train_loss`/`val_loss`/`eval_loss`), `f1_score`, `auc_roc`, `auroc`, `train_step`, `val_acc`, `eval_loss`, `epoch`, `gradient`, `tensor`, `overfit`, `generaliz`, `regulariz`, `validation`, `dropout`, `weight_decay`, `lr_schedule`, `cross_val`, `precision`, `recall`, OR explicit `--scientist` flag → `ml` → `research:scientist`
• contains `time`, `latency`, `bench`, `throughput`, `memory` → `perf` → `foundry:perf-optimizer`
• contains `pytest`, `coverage`, `complexity` → `code` → `foundry:sw-engineer`
• no keyword match → `perf` (default fallback) — rationale: perf-optimizer profiles before changing and is the least assumption-laden generic improver; code/ml metrics are reliably keyword-detectable, so an unmatched goal is most often timing-shaped. **WARN**: print `⚠ No keyword match — defaulting to 'perf' strategy. If this is an ML task, set agent_strategy: ml in program.md.` Log resolved agent + reason in state.json `strategy_resolution`.

Bare tokens `eval`, `train`, `val` (without compound s