Refine

Refine

Use Gear as the authority for evolution state, candidate workspaces, evaluation, selection, and promotion. This skill is the Meta Agent entrypoint; the Target Agent runs separately through the rollout provider configured in Gear.

Connect

Use the native refine_request tool when it is available. It carries the same protocol as the CLI and binds the current DSH session's client and configured runtime/skill identity after verifying the packaged skill was loaded; pass only the method and its ordinary parameters, with no clientId or identity. If the bridge reports missing instructions (for example after compaction), reload refine with DSH's native skill tool before retrying. In Code Mode, finish the skill-loading call before making a separate Refine request. This does not change or attest the host session's other tools, history, or OS permissions; those remain the host's responsibility.

Otherwise require all of the following before starting or claiming work:

• the gear-refine executable;
• GEAR_REFINE_SOCKET, unless the user supplies --socket;
• a stable client id for this harness session;
• the exact runtime, skill, model, and sampling identity configured for the evolution.

Do not guess an identity or silently change it. Gear seals it into the evolution spec and rejects a different harness on claim or resume.

Read references/protocol.md before constructing calls or handling an active assignment. Before diagnosing evidence or changing a candidate, also read references/target-harness-editing.md. When the candidate is Gear's DSH carrier, also read references/dsh-target-harness.md before choosing an artifact or hook. These references are the complete method contract, general editing guide, and version-specific DSH authoring guide; do not infer missing field names or harness APIs from errors.

Run an evolution

1. Inspect existing status before creating a new evolution when the user's wording could mean continue. A plain refine request creates a new evolution; continuation must name the evolution explicitly.

2. Call control.start or control.continue, then poll control.status and meta.claim. Baseline evaluation can finish before an assignment appears. Translate optimization preferences into control.start.objective.terms and optional explicit constraints. For example, equal pass/process weights are two terms with weight 0.5; cost/token penalties use negative weights and fixed scales in their original units. Do not put a different objective only in the prompt, invent a metric, infer passes from positive rewards, or alter the objective during search. Omission means strict pass rate. Check the returned resolvedObjective; inspect available raw metrics if admission rejects a term.

3. Treat the returned lease id, token, session id, candidate id, and (for CLI clients) client id as one inseparable capability. Never reuse them for another assignment.

4. Use only the candidate file and meta.call methods exposed by Gear. The direct candidate methods are exactly candidate.tree, candidate.read, candidate.write, candidate.edit, and candidate.remove. Invoke harness.current, harness.read, seed_tasks.load, trajectory.query, experience.query, experience.read, hitch.status, candidate.diff, candidate.check, candidate.finalize, and candidate.decline only as meta.call capabilities; they are not top-level request methods. Read the active candidate files before selecting an edit. Do not discover or modify Gear state, Git metadata, held-out data, credentials, or host paths directly.

5. Review the assignment's optional experienceContext. It contains the actual paired seed result of the direct parent's last edit when available, plus only relevant bounded history cards. Treat rationale and expected outcome as the earlier proposer's claims; treat task reward changes as observations, not causal or statistically significant conclusions. Use experience.query and experience.read for focused history. Historical experienceRef values never belong in evidenceRefs and never satisfy the active baseline diagnosis requirement.

6. Review the baseline summary. Also read baseline.rawMetrics and baseline.objectiveScore when present: the raw scores, units and contributions explain the frozen objective. A successful but expensive task can still warrant an improvement. State which measured term the proposal is expected to improve and verify its explicit constraints. Never replace a missing metric with zero or change the weights. If the assignment contains workplanDelivery, consume its hypothesis, parent identity, sourced dossier excerpt, scope guards, generation budget, and seed-only findings first. Keep modifications within workplan.modificationPaths (paths relative to the harness root), or explicitly disclose the wider effect; a narrow scope does not qualify wider changes for promotion. The claimed assignment records workplan-dossier-consumed, not personal diagnosis of all parent failures. When evidencePolicy.diagnoseEveryFailedRunBeforeProposal is false, the full-failure reading loop below does not apply: read extra seed evidence only when needed, and use candidate.check to confirm finalization readiness. Do not request or use held-out promotion details to plan candidate changes.

   For assignments without a workplan, start with trajectory.query without arguments on every assignment: it restores validated diagnostics from earlier attempts of this candidate and returns their summaries plus current-session detail refs. If diagnosisRecovery.remaining is positive, repeat that query to receive the rest. Use diagnosisProgress.remainingRunIds to choose new reads. Recovery does not restore candidate edits; inspect the current tree. Changed baseline, trajectory, verifier, or sanitization policy requires reading the affected evidence again. generationBudget reports attempt/round deadlines and remaining time. Its finalization reserve is advisory time for editing, checking, and sealing; it does not extend the deadline. Reconnecting does not reset time. A DIAGNOSIS_BUDGET_AT_RISK warning means the observed pace may leave too little time for the remaining work; do not skip required diagnoses or assume that continuing an old evolution adopts new budget settings. Query trajectory.query with refs for every remaining failed baseline run before proposing a change. It returns a compact diagnostic card containing the task, outcome, verifier failure summary, and the chronological message transcript without raw chunk noise. The card keeps the last 80,000 transcript characters and previews each tool result at up to 2,000 characters. Follow earlierRef for messages before that window and detailRef for a complete long result. Treat result_only as missing verifier logs, not as a complete failure explanation. When the card includes a detailRef, pass it back to trajectory.query; pass a returned nextRef back as the next detailRef, or add find to search that long content. Keep cited evidence limited to references actually returned for the active seed baseline. Start with one diagnostic card and size later reads from its actual output. Process the evidence before fetching more; use targeted detail reads instead of accumulating transcripts that repeatedly force context compaction.

7. Identify an evidenced harness gap before choosing an intervention. A failed task or omitted check alone does not establish that gap. Use relevant accessible seed comparisons to test the explanation, including successful runs when useful. Choose the smallest supported mechanism from the editing guide, with an applicability boundary that transfers beyond the observed tasks. New files are allowed but must be wired into the existing load graph. Prompt changes, skills, hooks, and workflows need the same causal support; do not force any artifact type. An implementation mistake can still expose a reusable prevention or detection opportunity; existing guidance alone does not show that an effective procedure or check exists. Apply the editing guide's diagnosis before either choosing a prompt edit or declining. Record the evidence, mechanism choice, applicability, and main uncertainty in rationale, and an observable behavioral prediction in expectedOutcome.

8. Inspect candidate.diff, remove accidental or task-specific changes, and run candidate.check before finalizing and require finalizationReadiness.ready: true. Inspect each runtime stage: loading, prompt assembly and Skill reads cover different paths; they do not prove that arbitrary tool/hook bodies, routing, compaction or workflows executed. Record remaining behavior checks in the proposal. Use candidate.decline when the evidence does not justify a harness change or the required fix is outside the editable substrate.

9. After finalization, stop using that lease and poll status. Claim and complete every subsequent candidate or round until the requested batch reaches a terminal state.