@evo-hq/pi-evo 0.5.0-alpha.11 → 0.5.0-alpha.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evo-hq/pi-evo",
-  "version": "0.5.0-alpha.11",
+  "version": "0.5.0-alpha.12",
   "description": "Evo plugin for pi-coding-agent: optimize/discover/subagent skills + mid-run inject extension.",
   "publishConfig": {
     "access": "public"

package/skills/discover/SKILL.md

@@ -2,7 +2,7 @@
 name: discover
 description: Initialize evo for the current repository by exploring the codebase, proposing unexplored optimization dimensions, constructing the benchmark inside a baseline worktree, and running the first experiment. Use when the user invokes /evo:discover, mentions setting up evo, wants to instrument a codebase for autonomous optimization, or asks to start a new evo run on a project.
 argument-hint: <optional context about what to optimize>
-evo_version: 0.5.0-alpha.11
+evo_version: 0.5.0-alpha.12
 ---
 
 # Discover
@@ -116,20 +116,20 @@ evo --version
 The output must be exactly:
 
 ```
-evo-hq-cli 0.5.0-alpha.11
+evo-hq-cli 0.5.0-alpha.12
 ```
 
 Three outcomes:
 
 1. **Matches exactly** — continue to step 1.
 2. **Reports a different version** (`evo-hq-cli 0.4.2`, etc.) — the host refetched a newer/older skill bundle than the CLI on PATH. Drift breaks skills silently. Stop and tell the user:
-   > Your installed evo CLI is on a different version than this skill (`0.5.0-alpha.11`). Run:
+   > Your installed evo CLI is on a different version than this skill (`0.5.0-alpha.12`). Run:
    > ```
-   > uv tool install --force evo-hq-cli==0.5.0-alpha.11
+   > uv tool install --force evo-hq-cli==0.5.0-alpha.12
    > ```
    > Then re-invoke this skill.
 3. **`command not found`, or reports a different package** (commonly `evo 1.x` — the unrelated SLAM tool) — the CLI isn't installed. Tell the user:
-   > `evo-hq-cli` isn't on your PATH. Install it: `uv tool install evo-hq-cli==0.5.0-alpha.11` (or `pipx install evo-hq-cli==0.5.0-alpha.11`). Then re-invoke this skill.
+   > `evo-hq-cli` isn't on your PATH. Install it: `uv tool install evo-hq-cli==0.5.0-alpha.12` (or `pipx install evo-hq-cli==0.5.0-alpha.12`). Then re-invoke this skill.
 
 Do not try to auto-install. Host sandbox + network policy may block it; leaving the install as a user action keeps failure modes clear.
 
@@ -308,10 +308,10 @@ Dashboard live: http://127.0.0.1:8080 (pid 12345)
 **Benchmark commands must be eval-only.** Do NOT wrap training and evaluation into a single benchmark command. If your benchmark command runs training before scoring, every gate revalidation and every `evo run --check` retrains from scratch, and the experiment budget burns on duplicated training instead of new experiments. Training is a separate step the agent invokes BEFORE `evo run`:
 
 1. The agent makes changes (data curation, hyperparameter selection, technique choice, training code edits).
-2. The agent runs training to produce a checkpoint at the experiment worktree's `final_model/` (or wherever the technique's recipe in `evo:finetuning/references/glue.md` specifies).
-3. THEN `evo run <exp_id>` invokes the registered benchmark command, which loads the produced checkpoint and emits a score.
+2. The agent runs the build/training step to produce its artifact — a checkpoint, adapter, index, whatever the recipe makes. Write it to `EVO_CHECKPOINT_DIR` (durable: survives between-attempt cleanup and discard) and declare it in the benchmark result's `artifacts` field so it's preserved + reusable; the per-technique I/O contract is in `evo:finetuning/references/glue.md`. Never hardcode a fixed name like `final_model/`.
+3. THEN `evo run <exp_id>` invokes the registered benchmark command, which loads the produced artifact and emits a score.
 
-The registered benchmark command should call `evaluate.py`, `run_eval.py`, or equivalent -- NOT `train.py`. If the project's only existing evaluation tool runs train+eval together with no eval-only mode, wrap it: add a `--skip-train` flag, or have the wrapper detect an existing checkpoint at `final_model/` and short-circuit the train step. Without this, evo's gate-recheck and re-score mechanics retrain repeatedly and the budget evaporates.
+The registered benchmark command should call `evaluate.py`, `run_eval.py`, or equivalent -- NOT `train.py`. If the project's only existing evaluation tool runs build+eval together with no eval-only mode, wrap it: add a `--skip-build` flag, or have the wrapper detect an existing artifact (under `EVO_CHECKPOINT_DIR`) and short-circuit the build step. Without this, evo's gate-recheck and re-score mechanics rebuild repeatedly and the budget evaporates.
 
 **Runtime environment.** If the benchmark needs keys or other runtime variables, configure them through evo rather than copying `.env` into worktrees or hand-editing `config.json`:
 
@@ -323,6 +323,16 @@ evo env show
 
 Values are resolved fresh by the orchestrator on each `evo run`. Config stores dotenv source metadata and key names, not secret values. The benchmark and gates receive the resolved env; gates do not receive `EVO_*` artifact variables.
 
+### 7a. Record the task category (`task-skills`)
+
+You already decided what's being optimized (steps 2–4). Record the evo category skill(s) a builder should load for it, so every executing agent — prose subagent or workflow lane — loads the right method knowledge instead of rediscovering it each round:
+
+```bash
+evo config set task-skills finetuning   # any weight-update / training task
+```
+
+Rule of thumb: if the optimization updates model weights (SFT / LoRA / DPO / RL / continued-pretraining), set `task-skills finetuning`. **Leave it unset** for prompt / code / config / harness optimization — the subagent protocol already covers those; only set it when a dedicated category skill applies. Use a comma-separated list if more than one applies. Mirror the choice in `.evo/project.md` (step 12) so it's human-readable and survives as the fallback if config is ever cleared.
+
 ## 8. Set up gates
 
 Gates inherit down the experiment tree -- children automatically get all ancestor gates.

package/skills/infra-setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: infra-setup
 description: Non-user-invocable provider/setup reference for evo backend switching, prerequisite checks, and auth/install guidance.
-evo_version: 0.5.0-alpha.11
+evo_version: 0.5.0-alpha.12
 ---
 
 # Infra Setup

package/skills/optimize/SKILL.md

@@ -2,7 +2,7 @@
 name: optimize
 description: Drive structured autoresearch iteration after evo:discover and the baseline commit -- scan-subagent cross-cutting analysis between rounds, frontier-based parent selection, ideator dispatch on stall, verifier pre/post hooks, annotation discipline. Width is set via subagents=N (1 for serial workloads, larger for parallel); the loop's structural value applies at any width.
 argument-hint: "[subagents=N] [budget=N] [stall=N]"
-evo_version: 0.5.0-alpha.11
+evo_version: 0.5.0-alpha.12
 ---
 
 Run the `evo` optimization loop. Each round, the orchestrator writes structured briefs and spawns subagents that execute within them. Each subagent is semi-autonomous: it reads the pointer traces, forms the concrete edit, runs experiments, and can iterate within its branch. Runs until interrupted or the stall limit is reached.

package/skills/optimize/workflows/evo-optimize.js

@@ -65,6 +65,8 @@ const STATE = {
     committedCount: { type: 'integer' },    // total committed experiments (drives the periodic ideator trigger)
     verifyRepeats: { type: 'integer' },     // benchmark noise profile (1 = deterministic, no confirm-loop)
     summary: { type: 'string' },            // short scratchpad summary for subagent context
+    taskSkills: { type: 'array', items: { type: 'string' } },     // category skills a builder should load (e.g. ["finetuning"]) — resolved from config/project, never hardcoded in the workflow
+    knownLearnings: { type: 'array', items: { type: 'string' } }, // durable lessons to apply up front (drained from annotations) so a fresh stateless lane doesn't rediscover them
   },
 }
 
@@ -181,10 +183,27 @@ const PREVERDICT = {
 // Analyst tick output: work-quality hints (fed into the next brief) + runtime/host alerts (surfaced).
 const ANALYST_FINDINGS = {
   type: 'object',
-  required: ['briefHints', 'alerts'],
+  required: ['briefHints', 'alerts', 'stops'],
   properties: {
     briefHints: { type: 'array', items: { type: 'string' } },
     alerts: { type: 'array', items: { type: 'string' } },
+    // STOP recommendations for in-flight experiments that are clearly doomed.
+    // A stop is NOT a crash: each carries the diagnosis + a fix so the gated
+    // enforcer can abort, annotate (lesson outlives the worktree), and classify+
+    // preserve — and the fix feeds the next round (and, if general, a skill prior).
+    stops: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['expId', 'failureClass', 'reason', 'fixHint'],
+        properties: {
+          expId: { type: 'string' },
+          failureClass: { enum: ['build', 'eval', 'hypothesis'] },
+          reason: { type: 'string' },    // what's wrong + the concrete evidence
+          fixHint: { type: 'string' },   // what the NEXT experiment must change
+        },
+      },
+    },
   },
 }
 
@@ -281,11 +300,14 @@ function statePrompt() {
     'Read-only. Do NOT edit files or run experiments. Run these and parse their output:',
     '`evo scratchpad`, `evo frontier` (already prints a JSON envelope), `evo status`, `evo awaiting`.',
     'Also read `.evo/project.md` for the metric goal, direction, and the benchmark-determinism line.',
+    'Also run `evo config get task-skills` (if unset/blank, infer the task category from project.md) and read recent `evo annotations` for durable learnings already found this run.',
     'Return: bestScore + bestExpId; the theoretical ceiling (1.0 for max metric, 0.0 for min)',
     'and direction; the frontier nodes ALREADY ranked by the configured strategy',
     '(id, score, rank) — preserve evo\'s ordering, do not re-rank; the list of evaluated-but-',
     'undecided experiment ids; committedCount (number of committed experiments, from `evo status`);',
     'verifyRepeats (from project.md: 1 if deterministic, 3 if sampling-based / variance-expected);',
+    'taskSkills (category skills a builder should load, e.g. ["finetuning"] — from `evo config get task-skills`, else inferred from project.md);',
+    'knownLearnings (short durable lessons from annotations to apply up front: trainer-API quirks, device placement, eval-side config, etc.);',
     'and a 2-3 sentence scratchpad summary for subagent context.',
   ].join(' ')
 }
@@ -305,6 +327,7 @@ function scanBrief(batch) {
     '- Shared failure causes -- root-cause reasons recurring across 2+ experiments (the *why*, not the surface gate name).',
     '- Wall patterns -- approaches or gates multiple experiments consistently fail on.',
     '- Compound-failure standouts -- single experiments hitting multiple failure modes.',
+    '- Axis exhaustion vs fixable plumbing -- read each node\'s `failure_class` (build|eval|hypothesis) from outcome.json. A cluster of `hypothesis` failures across STRUCTURALLY DISTINCT approaches means the axis itself is unpromising (flag it so the next briefs diverge); `build`/`eval` failures are fixable plumbing (recipe/scoring) and must NOT be read as axis exhaustion.',
     '',
     'Evidence must be VERBATIM quotes from outcome.json fields, trace messages, or error text -- not paraphrases. If you cannot cite verbatim evidence for a finding, drop it. Evidence: short quotes (<200 chars), max 3 per finding.',
     'Return JSON only: {"findings":[{"description","experiment_ids":[],"evidence":[]}]}.',
@@ -326,6 +349,10 @@ function aggregatePrompt(ids) {
     '~the same score (a plateau), the bottleneck is not where those hypotheses aimed — emit kind:"axis-warning" whose',
     'label names the saturated axis AND suggests the orthogonal axis (harness, score definition, input data, or a',
     'different mechanism) the next briefs should pivot to. At most one axis-warning.',
+    'Also read DISCARDED nodes (`evo discards` + their outcome.json `failure_class`): a cluster of 3+ failure_class="hypothesis"',
+    'discards across STRUCTURALLY DISTINCT approaches is itself an axis-warning (the direction keeps not helping). IGNORE',
+    'failure_class="build"/"eval" discards for axis purposes — those are fixable plumbing (retry/resume or eval-retest), not',
+    'evidence the axis is wrong.',
     'Return JSON only.',
   ].join(' ')
 }
@@ -356,9 +383,24 @@ function briefPrompt(state, findings, patterns, parents, ideated, analystHints)
 }
 
 // IMPLEMENT — allocate + edit, but do NOT run (a pre-run verifier audits the edit first).
+// Context capsule shared by every builder/runner lane: which category skills to load on demand,
+// and the durable learnings to apply up front — so a fresh stateless agent inherits the priors and
+// hard-won lessons a prose single-subagent would have had, instead of rediscovering them.
+function capsuleLines(state) {
+  const skills = (state && state.taskSkills) || []
+  const learnings = (state && state.knownLearnings) || []
+  const lines = []
+  lines.push(skills.length
+    ? `Task-category skills — load IN FULL via your host skill loader if the work needs them (they carry this category's priors, recipes, and pre-run checks): ${skills.join(', ')}.`
+    : "Identify the task category from `.evo/project.md` and load the matching evo skill (e.g. evo:finetuning for a training move) IN FULL before you build — it carries this category's priors and pre-run checks.")
+  if (learnings.length) lines.push(`KNOWN LEARNINGS to apply before acting (already found this run — do not rediscover): ${JSON.stringify(learnings)}.`)
+  return lines
+}
+
 function implementPrompt(brief, parent, state) {
   return [
     `First, load and follow the evo subagent skill: Read ${pr}/skills/subagent/SKILL.md IN FULL and follow it as your operating protocol — do not skip it even if the brief looks simple.`,
+    ...capsuleLines(state),
     `Allocate your experiment via \`evo new --parent ${parent}\`, then edit inside the returned worktree to implement the brief.`,
     'IMPORTANT: do NOT run `evo run` yet — a pre-run verifier audits your change first. Stop once the edit is complete.',
     'Do NOT edit benchmark, gate, or framework code; do NOT weaken/bypass any gate.',
@@ -397,12 +439,14 @@ function revisePrompt(expId, worktree, findings) {
 }
 
 // RUN — evaluate + commit the (pre-verified) experiment.
-function runPrompt(expId) {
+function runPrompt(expId, state) {
   return [
     `First, load the evo subagent skill: Read ${pr}/skills/subagent/SKILL.md IN FULL and follow its run protocol (it covers \`evo run ${expId} --check\` for non-committing wiring validation that does not consume the attempt budget).`,
-    `CRITICAL ordering: if this experiment produces its artifact through a build or training step (e.g. a finetune that writes final_model/), run that step to COMPLETION and confirm the artifact exists BEFORE the real run. Never call \`evo run\` while training is still in flight or before final_model/ exists — evaluating a not-yet-produced model is the "final_model not found" failure and it wastes the attempt. If the experiment trains, the parent checkpoint is in EVO_PARENT_POLICY (warm-start from it; do not retrain from base).`,
+    ...capsuleLines(state),
+    `CRITICAL ordering: if this experiment produces an output artifact through a build or training step (whatever your recipe declares — a checkpoint dir, adapter, merged model, index, etc.), run that step to COMPLETION and confirm the artifact exists BEFORE the real run. Never call \`evo run\` while that step is still in flight or before its output exists — evaluating a not-yet-produced artifact wastes the attempt. If the experiment warm-starts, the parent's reusable artifact is in EVO_PARENT_POLICY (start from it; do not redo from scratch).`,
     `Then run \`evo run ${expId}\` to evaluate and (if it improves and passes gates) commit it.`,
     'If it exits GATE_FAILED, do not fight the gate — report status=evaluated.',
+    'If `evo run` is terminated externally mid-flight (the concurrent analyst can STOP a doomed experiment — it aborts the run and discards this node with a diagnosis), do NOT retry: report status:none and stop. The diagnosis is already recorded as an annotation and will steer the next brief.',
     `Return: expIds:["${expId}"]; status (committed|evaluated|failed|none); committedImprover = true ONLY if evo printed COMMITTED;`,
     'bestExpId + bestScore (required when committedImprover is true); any gates added; learnings.',
   ].join(' ')
@@ -468,7 +512,9 @@ function analystPrompt(ctx, intervalS, reported) {
     '- Stuck experiment / time-budget overrun: from `evo status`/`evo show`, an experiment active far longer than its peers, or a round overrunning the others. ALERT.',
     '- Stuck axis: from `evo tree`, 3+ structurally-distinct committed hypotheses plateaued at ~the same score → name the saturated axis + one orthogonal axis. BRIEF HINT.',
     '- Dead direction / ignored mechanism: annotations repeatedly naming a mechanism the recent work ignores, or a direction that keeps regressing. BRIEF HINT.',
-    'Return {briefHints:[...], alerts:[...]}. briefHints feed the NEXT round\'s briefs (work-quality redirections); alerts surface to the user (runtime/host issues). Empty arrays are fine — most ticks should be quiet.',
+    '- Heading toward failure (STOP): an in-flight experiment that is CLEARLY doomed or wasting the budget — a divergent / NaN / flatlined progress metric; projected completion beyond the remaining time budget; or a known-fatal signature (e.g. output the scorer cannot parse; a silent resource mis-placement that tanks throughput with no error; a corrupt input/format that invalidates the result). HIGH PRECISION ONLY: default to NOT stopping — recommend a STOP only with concrete evidence that finishing is wasted, and only for an experiment still `active`. Emit a stop with: expId; failureClass (build = the build/produce step is broken; eval = artifact is fine but scoring/serving is wrong; hypothesis = it runs but won\'t help); reason (the diagnosis + the evidence you saw); fixHint (what the NEXT experiment must change).',
+    'You stay READ-ONLY: do NOT run `evo abort` / `evo discard` yourself. A gated enforcer acts on each stop — it aborts the run + its subprocess tree, annotates your diagnosis (so it outlives the worktree and feeds the next round), and discards with the failureClass so the partial artifact is preserved. A STOP is a diagnosed, recoverable stop, never a silent kill.',
+    'Return {briefHints:[...], alerts:[...], stops:[...]}. briefHints feed the NEXT round\'s briefs; alerts surface to the user; each stop triggers the gated enforcer (and its fixHint also feeds the next brief). All-empty is fine — most ticks should be quiet.',
   ].join('\n')
 }
 
@@ -476,6 +522,16 @@ function analystPrompt(ctx, intervalS, reported) {
 // iteration budget (deepening the branch each time a committed improver lands). The independent
 // evo:verifier gates EACH run for design-time cheating BEFORE the experiment is evaluated; its
 // findings are fed back to a revise agent on the same experiment until it passes or is discarded.
+//
+// Lane decomposition (decompose only at CONTEXT SEAMS): build+eval are a SINGLE agent — `run`
+// produces the artifact and evaluates it end-to-end (one coherent context, no handoff mid-build).
+// The only split is `implement` (write the edit) vs `run`, separated by the read-only evo:verifier
+// seam — a genuinely different concern (adversarial diff audit, different agentType/model) that has
+// to interpose between the edit and the expensive run. The two share state by REFERENCE (the
+// worktree on disk), not by passing a context window, and BOTH receive the capsule (category skills
+// + known learnings via capsuleLines), so neither reverts to base-model defaults. Merging implement
+// into run would erase the verifier gate for no real gain, since the code already lives in the
+// worktree the run agent reads.
 async function runBrief(brief, state) {
   let parent = brief.parent
   let best = null
@@ -504,7 +560,7 @@ async function runBrief(brief, state) {
     }
 
     // run -> evaluate + commit
-    const r = await agent(runPrompt(impl.expId), { schema: SUBAGENT_RESULT, phase: 'Optimize', label: `run:${impl.expId}` })
+    const r = await agent(runPrompt(impl.expId, state), { schema: SUBAGENT_RESULT, phase: 'Optimize', label: `run:${impl.expId}` })
     if (!r) break
 
     // post-run validity audit (evo:verifier, post-phase) on committed improvers
@@ -630,6 +686,23 @@ async function optimizeLoop() {
 // DURING rounds (not per-round). Each tick is a FRESH agent (no cross-tick memory), so `reported`
 // holds the dedup state in this closure. Work-quality findings -> analystSignals (next brief);
 // runtime/host alerts -> the run log. Stops when optimizeLoop sets `done`.
+// Gated ENFORCER for an analyst STOP: detect (analyst) and act (this agent) stay separate. Verifies
+// the experiment is still active, then aborts its run (driver + subprocess tree), annotates the
+// diagnosis (survives the worktree + feeds the next round via knownLearnings), and discards with the
+// failure class so the partial artifact is preserved + classified. A STOP is a diagnosed, recoverable
+// stop — never a silent kill.
+function enforceStopPrompt(s) {
+  return [
+    `A concurrent analyst flagged experiment ${s.expId} as heading toward failure and recommends STOPPING it. You are the gated ENFORCER — read-only except for the three evo commands below; do NOT edit code or run training.`,
+    `First VERIFY: run \`evo show ${s.expId}\`. Only proceed if its status is still \`active\`. If it is committed / evaluated / discarded / not found, do NOTHING and report skipped (it already resolved).`,
+    `If still active, run in order:`,
+    `  1. \`evo abort ${s.expId}\` — stop the evo run driver and its subprocess tree.`,
+    `  2. annotate the diagnosis so it outlives the worktree and feeds the next round: \`evo annotate ${s.expId} "STOPPED (${s.failureClass}): ${s.reason} | FIX: ${s.fixHint}"\` (quote carefully).`,
+    `  3. classify + preserve: \`evo discard ${s.expId} --force --failure-class ${s.failureClass} --reason "analyst stop: ${s.reason}"\` (--force because abort already killed the driver; declared artifacts are preserved).`,
+    `Report what you did (aborted / annotated / discarded) or that you skipped because it was no longer active. This is a diagnosed, recoverable stop, not a crash.`,
+  ].join('\n')
+}
+
 async function analystLoop() {
   if (!ANALYST_ENABLED) return
   const reported = []   // closure memory across the stateless ticks (caps re-alerting)
@@ -651,6 +724,21 @@ async function analystLoop() {
       fails = 0   // a real tick resets the failure streak
       for (const h of (tick.briefHints || [])) { analystSignals.push(h); reported.push(h) }
       for (const a of (tick.alerts || [])) { log(`ANALYST ALERT: ${a}`); reported.push(a) }
+      // STOP recommendations: hand each to a gated enforcer (detect/act separation). The fix also
+      // feeds the next round's brief so the loop corrects rather than just abandons.
+      for (const s of (tick.stops || [])) {
+        if (!s || !s.expId) continue
+        const stopKey = `stop:${s.expId}`
+        if (reported.includes(stopKey)) continue   // never re-enforce the same experiment
+        reported.push(stopKey)
+        log(`ANALYST STOP: ${s.expId} [${s.failureClass}] ${s.reason}`)
+        analystSignals.push(`Experiment ${s.expId} was stopped (${s.failureClass}): ${s.reason} — next: ${s.fixHint}`)
+        try {
+          await agent(enforceStopPrompt(s), { phase: 'Analyst', label: `enforce-stop:${s.expId}` })
+        } catch (e) {
+          log(`ANALYST enforce-stop ${s.expId} errored (ignored): ${(e && e.message) || e}`)
+        }
+      }
     } else if (++fails >= ANALYST_MAX_FAILS) {
       // The pacing wait lives INSIDE the agent, so a tick that fails before sleeping (e.g. a schema
       // reject) leaves nothing to pace the retry — left unchecked the loop hot-spins agents. The

package/skills/report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: report
 description: Print the dashboard's dot chart (score over experiment order, status colors, best-path stair) inline in the terminal for every run in the workspace. Use when the user invokes /evo:report, asks for a quick score chart without opening the dashboard, or wants the scatter plot in chat output.
-evo_version: 0.5.0-alpha.11
+evo_version: 0.5.0-alpha.12
 ---
 
 # Report

package/skills/subagent/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: subagent
 description: Protocol that evo optimization subagents follow when dispatched from /optimize. Auto-loaded by spawned subagents via their host's skill loader. The orchestrator may also invoke this skill to understand the brief shape its dispatched subagents expect + what they're required to emit -- useful when writing briefs or debugging a subagent's behavior.
-evo_version: 0.5.0-alpha.11
+evo_version: 0.5.0-alpha.12
 ---
 
 # Evo Subagent Protocol
@@ -124,8 +124,10 @@ evo gate add <id> --name <name> --command "<command>"  # add a gate
 
 # Write paths used during iteration
 evo new --parent <id> -m "<hypothesis>"   # allocate sibling experiment
+evo new --parent <id> -m "<h>" --from-artifact <exp[:label]>  # seed from a preserved artifact (EVO_SEED_ARTIFACT)
 evo run <id> [--check]                    # run (or --check to validate without consuming attempts)
-evo discard <id> --reason "<text>"        # reject + park (keeps anchor ref)
+evo abort <id>                            # stop a mid-run experiment (driver + its subprocess tree)
+evo discard <id> --reason "<text>" [--failure-class build|eval|hypothesis]  # reject + park (keeps anchor ref)
 evo restore <id>                          # un-discard or un-prune
 evo annotate <id> [<task_id>] "<text>"    # per-attempt analysis
 evo set <id> --note "<text>" [--tag <t>]  # per-node note from orchestrator
@@ -138,6 +140,7 @@ see `references/cli-quick-reference.md` "Reading workspace state".
 ## First Steps
 
 1. Read `.evo/project.md` to understand the target, what can be changed, and how to interpret results.
+1a. **Load this task's category skill(s).** Run `evo config get task-skills`; for each name returned (e.g. `finetuning`), load that evo skill IN FULL via your host's skill loader before you form an edit — it carries this category's method priors, recipes, and pre-run checks. If it returns blank, infer the category from `.evo/project.md` and load the matching skill if one applies (the subagent protocol alone covers prompt/code/config tasks). Skipping this is how a builder reverts to base-model defaults and reintroduces known mistakes (wrong device placement, stale trainer APIs, eval-before-build).
 2. Read the scratchpad for current state: `evo scratchpad`
    It surfaces: best path (★-marked in the tree), frontier (strategy-ranked branchable nodes), evaluated nodes awaiting decision, gates, annotations, what not to try, infra events, and notes. The Drill-downs section at the bottom lists the read-only commands for going deeper on any section.
 3. Study the pointer traces from your brief:
@@ -246,6 +249,20 @@ portable progress files there. evo mirrors that directory back into
 restart from benchmark-owned checkpoint files, but it does not freeze/restore an
 arbitrary Linux process.
 
+**Declare reusable outputs as artifacts (any category).** If your experiment
+produces an expensive, reusable output — a checkpoint, an adapter, a built
+index, a compiled prompt, anything — write it to `EVO_CHECKPOINT_DIR` (durable:
+it survives between-attempt cleanup and discard) and name it in the benchmark
+result's `artifacts` field: `{"score": ..., "artifacts": {"<label>": "<path>"}}`.
+Declared artifacts are preserved when the node is discarded, so a later
+experiment can reuse them via `evo new --from-artifact <exp[:label]>` (the path
+arrives as `EVO_SEED_ARTIFACT`). Never hardcode a name like `final_model/` — the
+label is whatever your recipe declares. If a run is clearly heading toward
+failure mid-flight (divergent loss, projected budget blow-out, a known-failure
+signature), it can be stopped with `evo abort <id>` — that kills the driver and
+its subprocess tree, and a partial artifact already written to
+`EVO_CHECKPOINT_DIR` survives for reuse.
+
 **If the workspace was initialized with `commit_strategy=tracked-only` (the default for `--backend pool`):** `evo run` only commits modifications to *tracked* files. New files require an explicit `git add` from inside the worktree, then a shisa-kanko ack on the run command:
 
 ```bash
@@ -270,7 +287,10 @@ The ack flag is required when the worktree has any untracked, non-gitignored fil
 
   Then either:
   - Fixable edit-bug (off-by-one, wrong signature): edit the worktree and `evo run <id>` again. Bounded by `max_attempts` (default 3). Before retrying, compare your planned edit against the previous attempts' `outcome.json` on this same node -- if two earlier attempts hit the same gate, a small tweak won't fix it. When the cap is hit, run is refused -- you must discard.
-  - Hypothesis is wrong, no fix: `evo discard <id> --reason "..."` and branch a new experiment from the **original parent**.
+  - Otherwise discard, and **classify why** with `--failure-class` so the orchestrator can route reuse vs branch:
+    - **`eval`** — the produced artifact is good but the scoring / serving / decode config is wrong. Make sure the artifact was declared + preserved; a sibling can **retest it in seconds** via `evo new --from-artifact <id>` (arrives as `EVO_SEED_ARTIFACT`) instead of rebuilding. `evo discard <id> --reason "..." --failure-class eval`.
+    - **`build`** — the artifact-production step itself broke. Fix it, then retry/resume *from the last checkpoint in `EVO_CHECKPOINT_DIR`* rather than rebuilding from scratch. `evo discard <id> --reason "..." --failure-class build` only if you're abandoning this node.
+    - **`hypothesis`** — it ran clean but didn't help. `evo discard <id> --reason "..." --failure-class hypothesis` and branch a new experiment from the **original parent** (a different direction, not a retry of the same idea).
 
 - **`FAILED`** (infra error, non-zero exit, timeout): couldn't evaluate. Doesn't consume the retry budget.
   - Transient / fixable locally: retry.