orizu 0.5.21 → 0.5.22

package/vendor/skills/orizu-cli/references/cli-reference.md

@@ -80,23 +80,39 @@ orizu projects create --name "Quality Eval" --team my-team
 ### Instruction sets
 
 ```bash
-orizu instruction-sets list --project my-team/quality-eval [--status active|archived|all] [--json]
-orizu instruction-sets show <set> --project my-team/quality-eval [--status active|archived|all] [--json]
-orizu instruction-sets create ./orizu.instruction-set.json --project my-team/quality-eval [--runner-version <id>] [--model-config <identity>] [--json]
-orizu instruction-sets push ./orizu.instruction-set.json --project my-team/quality-eval [--runner-version <id>] [--json]
-orizu instruction-sets sync <set> --out ./instructions --project my-team/quality-eval [--model-config <identity>] [--json]
-orizu instruction-sets profiles new <set> --project my-team/quality-eval --model-config <identity> [--json]
-orizu instruction-sets profiles promote <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
-orizu instruction-sets profiles rollback <set> --project my-team/quality-eval --model-config <identity> --to <n> [--json]
-orizu instruction-sets default show <set> --project my-team/quality-eval [--json]
-orizu instruction-sets default move <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
-orizu instruction-sets shape add <set> --project my-team/quality-eval --key <key> --from <manifest> [--json]
-orizu instruction-sets shape remove <set> --project my-team/quality-eval --key <key> [--json]
+orizu instructions list --project my-team/quality-eval [--status active|archived|all] [--json]
+orizu instructions show <set> --project my-team/quality-eval [--status active|archived|all] [--json]
+# Human/local CLI only: a human runs create/push; hosted agents may run profiles new and sync.
+orizu instructions create ./orizu.instruction-set.json --project my-team/quality-eval [--runner-version <id>] [--model-config <identity>] [--json]
+orizu instructions push ./orizu.instruction-set.json --project my-team/quality-eval [--set <slug-or-exact-name>] [--runner-version <id>] [--json]
+orizu instructions sync <set> --out ./instructions --project my-team/quality-eval [--model-config <identity>] [--json]
+orizu instructions profiles new <set> --project my-team/quality-eval --model-config <identity> [--json]
+# Human/local CLI only: profile production-pointer moves.
+orizu instructions profiles promote <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
+orizu instructions profiles rollback <set> --project my-team/quality-eval --model-config <identity> --to <n> [--json]
+orizu instructions default show <set> --project my-team/quality-eval [--json]
+# Human/local CLI only: the set-wide default-pointer move.
+orizu instructions default move <set> --project my-team/quality-eval --model-config <identity> --version <n> [--json]
+# Human/local CLI only: shape mutations.
+orizu instructions shape add <set> --project my-team/quality-eval --key <key> --from <manifest> [--json]
+orizu instructions shape remove <set> --project my-team/quality-eval --key <key> [--json]
+# Human/local CLI only: visibility mutations.
+orizu instructions archive <slug-or-exact-name> --project my-team/quality-eval [--json]
+orizu instructions restore <slug-or-exact-name> --project my-team/quality-eval [--json]
 ```
 
-`list` returns each instruction set and its ordered shape. `show` returns the
-default and every model-config profile's production state. `create` and `push`
-read a local manifest; JSON output is one document per line.
+`instructions` is the customer-facing command namespace. The legacy
+`instruction-sets` spelling remains a compatibility alias, but new workflows
+should not teach it. A set can be addressed by its stable slug or exact name;
+the slug does not change when the display name changes. `list` returns each
+instruction set and its ordered shape. `show` returns the default and every
+model-config profile's production state. Use `--status archived` or `--status
+all` to include archived sets. A human curator runs create, push, shape,
+archive, and restore mutations from the local CLI with a user token. Archive
+and restore change visibility only:
+archived sets continue to resolve and sync. `create` and `push` read a local
+manifest; JSON output is one document per line. `push --set` updates the named
+or slug-addressed set independently of the manifest's display name.
 
 `profiles new` copies the default component map into a model-config profile without
 changing its production resolution; hosted agents may create this seed because
@@ -117,18 +133,28 @@ the default or a production label. The set does not resolve for affected model
 configs until those pointers move to the new shape-change profile versions; the
 text CLI prints the required follow-up commands.
 
-The manifest is a JSON object with `name`, ordered `shape`, and `components`.
-Every component supplies `{ key, text }` or `{ key, path }`; paths are relative
-to the manifest. Set-wide components must cover the complete shape. A component
-may add `modelConfig` for a profile override: `create` materializes that named
-profile with the set-wide component map plus its overrides, while `push` updates named
+The manifest is a JSON object with `name`, optional unversioned `description`,
+ordered `shape`, and `components`. The description belongs to the instruction
+set rather than any profile and round-trips through sync. Every component
+supplies `{ key, text }` or `{ key, path }`; paths are relative to the manifest.
+Set-wide components must cover the complete shape. A component may add
+`modelConfig` for a profile override: `create` materializes that named profile
+with the set-wide component map plus its overrides, while `push` updates named
 profiles already present on the set. `push` refuses a manifest whose shape
 differs from the stored set.
 
-`sync` writes `<out>/<set>/manifest.json`, `default/<key>.md`, and
+`sync` writes `<out>/<stable-set-slug>/manifest.json`, `default/<key>.md`, and
 `profiles/<identity-slug>/<key>.md` for offline execution. TypeScript runners
-use `loadInstructionSet(dir, name, modelConfigIdentity)` from `orizu`; Python
-runners use `orizu_gepa_connector.instruction_set_loader.load_instruction_set`.
+use `loadInstructionSet(dir, setReference, modelConfigIdentity)` from `orizu`;
+Python runners use
+`orizu_gepa_connector.instruction_set_loader.load_instruction_set`. Prefer the
+stable slug as `setReference`; both loaders also resolve the manifest's exact
+name for compatibility with directories synced before slugs shipped. The
+manifest's immutable `projectId` and `instructionSetId` prevent a shared
+`--out` root from replacing another project's same-slug set.
+Identity-less pre-slug trees cannot prove project ownership and are preserved;
+sync returns `instruction_set_sync_legacy_identity_required` until the operator
+moves the old tree aside or selects a clean output root.
 Both select that model config's production component map or the default without a
 network call. Git-pinned components have no local bytes: loading one raises
 `instruction_set_component_unavailable` until the runner supplies those bytes.
@@ -347,9 +373,12 @@ Defaults:
 - format defaults to `jsonl`
 - output file defaults to `<taskId>.<format>`
 
-### Prompt Control Plane
+### Instruction Control Plane
 
-For prompts, judges, runners, run submission, optimizer artifacts, live event logging, and accepted-candidate promotion, read `prompt-control-plane.md`. For markdown reports attached to optimization runs, read `optimization-reports.md`.
+For instruction sets, judges, runners, run submission, optimizer artifacts,
+live event logging, and accepted-candidate promotion, read
+`prompt-control-plane.md`. For markdown reports attached to optimization runs,
+read `optimization-reports.md`.
 
 Diff-comment export:
 
@@ -381,7 +410,7 @@ exist.
 Optimization trace commands:
 
 ```bash
-orizu optimizations run-gepa ... [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] [--candidate-selection-strategy pareto|current_best|epsilon_greedy] [--epsilon N] [--objective <text>] [--candidate-proposer skilled-proposer] [--proposal-max-calls N] [--proposal-max-tokens N] [--python <command>] [--num-threads auto|N] [--reflection-retry-attempts 3] [--reflection-http-timeout-seconds 180] [--log-dir logs] [--no-local-log]
+orizu optimizations run-gepa ... [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] [--candidate-selection-strategy pareto|current_best|epsilon_greedy] [--epsilon N] [--objective <text>] [--candidate-proposer skilled-proposer] [--candidate-proposer-config @file] [--proposal-max-calls N] [--proposal-max-tokens N] [--python <command>] [--num-threads auto|N] [--reflection-retry-attempts 3] [--reflection-http-timeout-seconds 180] [--log-dir logs] [--no-local-log]
 orizu optimizations export <optimization-run-id> --out ./optimization.json
 orizu optimizations export <optimization-run-id> --json
 ```
@@ -390,7 +419,7 @@ Behavior:
 - `run-gepa` sends the scorer runner a GEPA-shaped row (`{source_row, candidate_output, …}`) by default. Judge runners written for flat-row score runs (`runners exec --scorer-version`) need `--scorer-input-contract flat_row` (plus `--scorer-candidate-field <row-field>` when the judge reads the candidate output from a named row field) or they silently score everything 0. `run-gepa` validates the contract on the seed at launch and refuses a uniformly-worst seed unless `--allow-degenerate-seed` is set. See `prompt-control-plane.md` ("Scorer-Runner Input Contracts").
 - `run-gepa` defaults `--num-threads` to `auto`, resolving a row-evaluation parallelism cap from mini-batch size, validation-set size, 2x CPU count, memory estimate, file-descriptor limit, and a 64-thread default ceiling. Set `ORIZU_GEPA_AUTO_THREADS_MAX` or use `--num-threads <n>` only when the runner/provider capacity is known.
 - `run-gepa` retries transient reflection-provider failures by default. If retries are exhausted, it logs `reflection_failed`, counts that reflection proposal against budget, and continues with the next iteration.
-- The skilled proposer is official-engine-only and prepares its managed Python environment on the selected run. Flag validation, proposal budgets, and recovery: `prompt-control-plane.md` ("Skilled proposer").
+- The skilled proposer is official-engine-only and prepares its managed Python environment on the selected run. `--candidate-proposer-config @file` adds explicit skills/guidance and requires that selection; the selection itself is incompatible with `--reflection-prompt-template`. Schema, proposal budgets, and recovery: `prompt-control-plane.md` ("Skilled proposer").
 - `run-gepa` writes a complete local trace under `logs/<optimization_run_id>` by default.
 - The local trace is the best artifact for coding-agent analysis because it includes full rows, outputs, scores, feedback, scorer responses, reflection prompts, reflection responses, candidate text, and `result.json`.
 - `optimizations export` writes a portable JSON artifact from server data when the local log is unavailable or the run happened elsewhere.
@@ -481,7 +510,7 @@ Worker assignment reads are self-only:
 - Use `tasks status` and `tasks export` for operator-side reporting.
 ### Offline instruction-set sync
 
-`orizu instruction-sets sync <set> --project <team/project> --out <dir>` writes
+`orizu instructions sync <set> --project <team/project> --out <dir>` writes
 an atomic local manifest. A resolver failure for either the default or any
 selected profile refuses the entire sync as `instruction_set_unresolvable`; the
 route never silently downgrades a failed production component map to default bytes. A

package/vendor/skills/orizu-cli/references/instructions-after-prompts.md

@@ -0,0 +1,120 @@
+# Instructions After Prompts
+
+Use instruction sets for customer-owned model instructions. The older prompt
+read surface remains available for locating legacy artifacts, but standalone
+prompt content and production mutations deliberately redirect to `orizu
+instructions`.
+
+## Find Existing Material
+
+Legacy prompts appear as one-component sets in the instruction inventory:
+
+```bash
+orizu instructions list --project <team/project> --status all --json
+orizu instructions show <slug-or-exact-name> --project <team/project> --status all --json
+```
+
+Use prompt reads only when you need to correlate an old prompt identifier or
+download its files:
+
+```bash
+orizu prompts list --project <team/project> --status all
+orizu prompts pull <prompt-id-or-name> --project <team/project> --out ./legacy-prompt
+```
+
+The text output ends with the owning instruction set's stable slug and
+component key. List and pull include the prompt display name and identifier:
+
+```text
+Owner: Generator (prompt-1) -> planner-agent / system
+```
+
+Use the slug after `->` for instruction commands and the final segment for the
+component key. Address scorer bindings directly with that instruction-set slug
+and component key. An ownerless judge or draft prompt may have no owner line.
+
+## Understand Deliberate Refusals
+
+Standalone prompt content, production-pointer mutations, and prompt-addressed
+scorer bindings fail before making a request. The CLI prints these exact
+replacements:
+
+- `Use: orizu instructions push <manifest> --project <team/project>`
+- `Use: orizu instructions archive <slug-or-exact-name> --project <team/project>`
+- `Use: orizu instructions restore <slug-or-exact-name> --project <team/project>`
+- `Use: orizu instructions profiles promote <set> --project <team/project> --model-config <identity> --version <n>`
+- `Use: orizu instructions scorers set-headline <set> --key <component-key> --scorer-version <id> --project <team/project>`
+- `Use: orizu instructions scorers add <set> --key <component-key> --scorer-version <id> --project <team/project>`
+
+Older clients and direct API callers can reach two additional server-side
+prompt-write conflicts. Both fail closed with an exact JSON error:
+
+| Write path | Conflict | Measured response | Next action |
+| --- | --- | --- | --- |
+| Sessionless prompt registration from an older client or direct API call | The name has set-owned storage and no ownerless lineage. | 409 — `Use: orizu instructions push; prompt name belongs to an instruction set` | Use the owning set's manifest through `orizu instructions`; the current CLI redirects before HTTP. |
+| Session-scoped prompt draft (`prompts push ... --session ...`) | The name belongs to components in more than one instruction set and has no ownerless lineage. | 409 — `session draft prompt name is ambiguous across instruction sets` | Do not guess by name. Inventory the sets and component keys, then prepare the intended instruction-set manifest. |
+
+These client redirects and server conflicts do not apply to prompt reads, judge
+artifacts, prompt reports, instruction-addressed scorer bindings, unambiguous
+session-scoped drafts, or non-production prompt labels.
+
+## Agent preparation
+
+From a hosted session, inventory every active and archived set, choose a stable
+target name, component keys, model-config profiles, and complete component
+text, then prepare a manifest such as:
+
+```json
+{
+  "name": "planner-agent",
+  "description": "Instructions used by the planner agent.",
+  "shape": ["system", "tools"],
+  "components": [
+    { "key": "system", "path": "./system.md" },
+    { "key": "tools", "path": "./tools.md" }
+  ]
+}
+```
+
+Commit or otherwise hand the complete manifest and its component files to the
+human curator. Do not run an instruction-set mutation from the hosted session.
+
+## Human-run consolidation
+
+Consolidation changes ownership and visibility, so a human curator must run it
+from the local CLI with a user token. Create the consolidated set and inspect
+its complete profiles before changing any pointer:
+
+```bash
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu instructions create ./orizu.instruction-set.json --project <team/project> --model-config <identity> --json
+orizu instructions show <slug-or-exact-name> --project <team/project> --status all --json
+```
+
+After verifying the new set, the human archives each redundant one-component
+set. Archive changes visibility only; the archived set still resolves and
+syncs until the human pointer move is complete, so it remains a recovery
+source.
+
+```bash
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu instructions archive <slug-or-exact-name> --project <team/project> --json
+```
+
+The human must explicitly move the consolidated set's default or promote a
+named model-config profile. Coding agents stop after preparing the manifest and
+handoff details rather than running these commands:
+
+```bash
+# Human/local CLI only: the human curator moves these pointers.
+orizu instructions default move <set> --project <team/project> --model-config <identity> --version <n> --json
+orizu instructions profiles promote <set> --project <team/project> --model-config <identity> --version <n> --json
+```
+
+The human confirms the resolved default and every production profile after the
+move. If a redundant set must become visible again, the human restores it:
+
+```bash
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu instructions restore <slug-or-exact-name> --project <team/project> --json
+```

package/vendor/skills/orizu-cli/references/migrate-existing-gepa-setup.md

@@ -1,22 +1,29 @@
 # Migrating an existing GEPA setup into Orizu
 
 For a customer already running official GEPA from a plain script — inline
-`trainset`/`valset`, a seed prompt in a dict, their own `metric(row, output)`.
+`trainset`/`valset`, seed component values in a dict, and their own
+`metric(row, output)`. The dict becomes one instruction-set profile: its keys
+become the set's fixed shape, and its values become that profile's components.
+Use `orizu instructions` as the only creation and update path for those
+customer-owned instructions. A coding agent prepares the complete manifest;
+a human curator runs its mutations from the local CLI with a user token.
 
 The ordering rule: **nothing is optimized until parity is proven.** The last
 step before `run-gepa` is always `orizu scorers verify-parity`, which runs the
 migrated scorer runner under the exact payload `run-gepa` sends it and the
 customer's original metric over the same rows, and exits 0 only if they agree.
 
-Commands are shown with `--local`; drop it against a hosted server.
+Commands are shown with `--local`; drop it against a hosted server except for
+instruction-set mutations and pointer moves marked human-only, which a hosted
+agent prepares but never executes.
 
 ## 0. Read their script
 
 Note the row shape and which field is the stable id, `trainset`/`valset`
-membership, the seed candidate text, the metric's `module:function`, and what
-it returns (a float, a dict with `score`, or GEPA's `EvaluationResult` — all
-three are accepted; `objective_scores` is ignored). If rows have no stable id,
-add one now: every step below pairs on it.
+membership, the seed component map, the metric's `module:function`, and what it
+returns (a float, a dict with `score`, or GEPA's `EvaluationResult` — all three
+are accepted; `objective_scores` is ignored). If rows have no stable id, add
+one now: every step below pairs on it.
 
 ## 1. Set up, then export the rows
 
@@ -69,35 +76,48 @@ orizu --local datasets splits create <dataset-version-id> \
 `--from-file` preserves their partitions; the ratio flags
 (`--train/--validation/--test`) resample and must not be used here.
 
-## 3. Candidate runner and seed prompt
+## 3. Candidate runner and seed instruction set
 
-The candidate runner does what `task_lm` did: candidate prompt + row -> output.
+The candidate runner does what `task_lm` did: candidate profile + row ->
+output. A one-component profile keeps the single-body runner contract. For a
+multi-component profile, read the complete map from
+`input["instruction_set"]["components"]`; components belong only to this
+profile and are never shared across profiles or sets.
 
 ```bash
 orizu --local runners push ./candidate-runner \
   --project <team>/<project> --name gepa-candidate-runner --label default --json
 
-orizu --local prompts push ./prompt \
-  --project <team>/<project> --runner-version <candidate-runner-version-id> --json
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu --local instructions create ./orizu.instruction-set.json \
+  --project <team>/<project> \
+  --runner-version <candidate-runner-version-id> \
+  --model-config <provider/model> --json
 ```
 
-`./prompt` holds `orizu.prompt.json` plus the body file it names. Only `name`
-is enforced (`app/api/cli/prompts/route.ts:220-221`); `body_file` defaults to
-`prompt.md`, `body_kind` to `text` (`packages/cli/src/index.ts:3966-3985`) and
-`provider_settings` to `{}`. Write all four anyway — a migration whose model
-settings are implicit is a migration nobody can reproduce:
+The manifest carries the instruction set's `name`, human-readable
+`description`, fixed `shape`, and component values. Put each original dict
+value in a file without changing its bytes. This one-component example maps
+the old `system` key to `system.md`:
 
 ```json
 {
-  "name": "gepa-seed-prompt",
-  "body_file": "prompt.md",
-  "body_kind": "text",
-  "provider_settings": { "model": "claude-sonnet-4-6", "temperature": 0 }
+  "name": "gepa-agent-instructions",
+  "description": "Instructions for the migrated GEPA application",
+  "shape": ["system"],
+  "components": [
+    { "key": "system", "path": "./system.md" }
+  ]
 }
 ```
 
-`prompt.md` carries their seed candidate text verbatim. Returns the seed
-`prompt_version_id`.
+For a multi-component seed, list every original key once in `shape`, in stable
+order, and add one component entry per key. `--model-config` selects the
+profile whose seed is created; it must name an existing model config with the
+same settings used by the original script. The JSON result includes the set's
+stable `slug` and its default profile version. Record the slug — later reads,
+optimization, archiving, and restoration should use it even if the display
+name changes.
 
 ## 4. Wrap their metric in a scorer runner
 
@@ -157,12 +177,12 @@ def metric(row, model_output):                      # what verify-parity calls
 orizu --local runners push ./scorer-runner \
   --project <team>/<project> --name gepa-scorer-runner --label default --json
 
-orizu --local prompts push ./scorer-prompt \
+orizu --local judges push ./judge \
   --project <team>/<project> --runner-version <scorer-runner-version-id> --json
 
 orizu --local scorers register --project <team>/<project> \
   --name gepa-migrated-metric --manifest ./scorer.manifest.json \
-  --prompt-version <scorer-prompt-version-id> \
+  --prompt-version <judge-version-id> \
   --runner-version <scorer-runner-version-id> \
   --label production --json                        # -> scorer_version_id
 ```
@@ -180,29 +200,39 @@ or `metric_key`, and `mode` must be `row` or `set`:
 }
 ```
 
-`prompt_runner` is the only kind `runners exec --scorer-version` and
-`verify-parity` can execute, and it requires a backing prompt version. For a
-pure-code metric with no judge text, `./scorer-prompt` is a short prompt
-version documenting the rubric; the runner never reads its body.
+`prompt_runner` is the only implementation kind that `runners exec
+--scorer-version` and `verify-parity` can execute, and the scorer contract
+currently names its backing judge artifact with `--prompt-version`. That flag
+receives the `prompt_version_id` returned by `orizu judges push`; do not replace
+the judge command with a standalone prompt mutation.
 
-## 5. Produce `outputs.jsonl` by running the seed once
+For an LLM metric, `./judge` contains the evaluator rubric the scorer runner
+executes. For a pure-code metric, keep a short judge rubric that documents the
+deterministic rule and expected output, even though the runner does not read
+its body. The judge is the evaluator artifact; the scorer is the metric
+contract that gives its numeric result a name, mode, and direction.
 
-A scorer scores *(row, output)*, so parity needs one candidate output per row.
+## 5. Freeze the original setup's outputs
 
-```bash
-orizu --local runners exec \
-  --prompt-version <seed-prompt-version-id> \
-  --runner-version <candidate-runner-version-id> \
-  --dataset-version <dataset-version-id> \
-  --split-set <split-set-id> --split validation \
-  --out ./results.jsonl
+A scorer scores *(row, output)*, so parity needs one candidate output per row.
+Use the customer's existing script to run its original `task_lm` once with
+the unchanged seed component map, and record the exact output passed to
+`metric(row, output)`. Write one file per partition. Each JSONL row is:
 
-jq -c '{row_id: .row_id, model_output: .model_response}' ./results.jsonl > ./outputs.jsonl
+```json
+{"row_id":"<the row's stable id>","model_output":"<the exact output>"}
 ```
 
-`outputs.jsonl` must cover exactly the rows being checked: a missing or extra
-`row_id`, a duplicate, or a non-string `model_output` is refused before
-anything runs.
+Do not produce this evidence by running the migrated scorer or by starting an
+optimization. The output is a fixed subject shared by the original metric and
+the migrated scorer, so a mismatch isolates the scorer migration rather than
+mixing in candidate-runner or provider drift. After scorer parity is proven,
+characterize the candidate runner separately against these same rows before
+starting GEPA.
+
+Each partition's output file must cover exactly the rows being checked: a
+missing or extra `row_id`, a duplicate, or a non-string `model_output` is
+refused before anything runs.
 
 ## 6. Prove parity
 
@@ -211,7 +241,7 @@ orizu --local scorers verify-parity \
   --scorer-version <scorer-version-id> \
   --dataset-version <dataset-version-id> \
   --split-set <split-set-id> --split validation \
-  --outputs ./outputs.jsonl \
+  --outputs ./outputs-validation.jsonl \
   --original metric:metric \
   --json
 ```
@@ -237,9 +267,9 @@ orizu --local scorers verify-parity \
   the registered runner version; drifted bytes exit 2.
 - `--limit <n>` checks the first N rows of the partition — a smoke check, not
   the proof: it always reports `parity: false` with `scope: {compared, total}`,
-  so a limited run can never be mistaken for a full one. The same full
-  `outputs.jsonl` works: outputs must cover the limited rows and belong to the
-  split, and need not be trimmed to N.
+  so a limited run can never be mistaken for a full one. The full partition's
+  output file works: outputs must cover the limited rows, belong to the split,
+  and need not be trimmed to N.
 - A repeated option takes its LAST value, matching run-gepa's scalar options.
 - If a sampled row already has the candidate field as a key, the command exits 2
   rather than overwriting a value the original metric reads.
@@ -257,7 +287,8 @@ optimizes the wrong thing, and every number afterwards is wrong.
 proposals: a scorer that agrees on validation but diverges on a training row
 that exercises a different schema branch changes the experiment's result while
 passing this gate. Repeat steps 5 and 6 with `--split train` (its own
-`outputs.jsonl` from the same seed run) and require exit 0 on both.
+`outputs-train.jsonl` from the same frozen seed evaluation) and require exit 0
+on both.
 
 A `parity: true` report means every row of that partition was compared and
 agreed. A limited run reports `parity: false` with
@@ -273,7 +304,9 @@ orizu --local optimizers push ./optimizer \
 orizu --local optimizations run-gepa \
   --project <team>/<project> \
   --optimizer-version-id <optimizer-version-id> \
-  --candidate-version-id <seed-prompt-version-id> \
+  --instruction-set <instruction-set-slug> \
+  --model-config <provider/model> \
+  --component-selector round-robin \
   --runner-version-id <candidate-runner-version-id> \
   --candidate-runner-dir ./candidate-runner \
   --scorer-version-id <scorer-version-id> \
@@ -294,10 +327,37 @@ reflection model is refused at launch without it
 `packages/orizu-gepa/src/orizu_gepa_connector/runtime.py:193-196`). Drop it only
 if you also pass an `openai/...` `--reflection-model`.
 
+`--instruction-set` and `--model-config` select exactly one profile. The CLI
+uses that profile's production version when it has one and otherwise uses the
+set default; it refuses the legacy `--candidate-version-id` selector when the
+instruction-set selectors are present. `round-robin` updates one component per
+round; use `--component-selector all` only when every component should be
+reflected on each round.
+
 `./optimizer` needs `manifest.json` with `"optimizer_family": "gepa"`. See
 `references/optimization-with-gepa.md` for reflection-model and budget flags.
 Pass `--scorer-candidate-field <field>` here too if you passed it to
 `verify-parity`: the payload the runner sees must be the one parity was proven
-under. Afterwards, `orizu optimizations promote <run-id> --candidate <id>
---label production` promotes the winner — and with parity proven, its score is
-comparable to the seed score their own script reports.
+under. Afterwards, promote only a candidate that passed held-out validation.
+Copy the accepted candidate's complete component map back into the manifest's
+files, then prepare the exact commands for one new version of the selected
+profile. Both the push and the profile promotion are human-only: a coding agent
+prepares the validated manifest and exact handoff commands, but a human curator
+runs both from the local CLI with a user token.
+
+```bash
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu --local instructions push ./orizu.instruction-set.json \
+  --project <team>/<project> --set <instruction-set-slug> \
+  --runner-version <candidate-runner-version-id> --json
+
+# Human/local CLI only: the human curator moves the production pointer.
+orizu --local instructions profiles promote <instruction-set-slug> \
+  --project <team>/<project> --model-config <provider/model> \
+  --version <new-profile-version-number> --json
+```
+
+The push creates a complete profile version. After the human promotion, only
+that profile's production pointer has moved; a component is never promoted by
+itself. With parity proven, its score is comparable to the seed score their own
+script reports.

package/vendor/skills/orizu-cli/references/optimization-reports.md

@@ -5,12 +5,12 @@ Use this reference when writing the markdown report attached to an Orizu optimiz
 Attach the final markdown with:
 
 ```bash
-orizu optimizations finish <run-id> --best-candidate <candidate-id> --report-file ./reports/<run-id>.md
+orizu optimizations finish <run-id> --best-candidate <candidate-id> --result-prompt-version <prompt-version-id> --report-file ./reports/<run-id>.md
 orizu optimizations fail <run-id> --reason "<reason>" --report-file ./reports/<run-id>.md
 orizu optimizations cancel <run-id> --reason "<reason>" --report-file ./reports/<run-id>.md
 ```
 
-For budget-exhausted runs, `run-gepa` pauses the optimization before auto-promotion. Write the report from the paused run, then manually finish with `--best-candidate`, `--result-prompt-version` if promoted, and `--report-file` once the decision is made.
+For budget-exhausted runs, `run-gepa` pauses the optimization before auto-promotion. Coding agents may write the report and finish the paused run with `--best-candidate`, `--result-prompt-version` if the candidate version already exists, and `--report-file`. Finishing records the outcome but does not move a serving pointer. Only the pointer-moving `optimizations promote --label production` form is human-only; prepare that command for a human curator to run.
 
 ## Source Artifacts
 
@@ -30,7 +30,7 @@ Read them in this order:
 
 1. `result.json` for seed score, best score, best candidate id/text, promotion id, and budget state.
 2. `evaluations.jsonl` for fixed rows, regressions, persistent failures, per-row feedback, latency, cost, and cache state.
-3. `reflections.jsonl` for what the reflection model saw and why each child prompt was proposed.
+3. `reflections.jsonl` for what the reflection model saw and why each child candidate was proposed.
 4. `events.jsonl` for iteration order, candidate lineage, Pareto updates, budget events, pauses, failures, and promotions.
 
 If local logs are unavailable, export the server-side archive:
@@ -52,17 +52,22 @@ Include:
 - The headline scorer name, metric key, split, scorer version, and dataset split.
 - For judge alignment, prefer Cohen's kappa as the headline metric when labels are imbalanced. Kappa has an interpretable zero point: 0 is chance agreement, negative is worse than chance, and positive means real discrimination.
 - Always include the confusion matrix alongside kappa. On small validation sets, the matrix movement often matters more than the single estimate.
-- Promoted prompt version id, promotion label, and Orizu dashboard link when available.
+- Promoted instruction-set profile version, model config, set slug, and Orizu dashboard link when available.
 - Small-n uncertainty note when `n < 30`. For example, at `n = 15`, a rough kappa standard error can be about +/- 0.25, so call out directional signals rather than overclaiming precision.
 
 ### 2. What The Optimizer Changed
 
 Summarize the seed body -> best body diff in bullets rather than pasting a full raw diff. For each notable change, mark it as:
 - Targeted fix: addresses a specific failure cluster found in train/validation feedback.
-- General restructure: reorganizes the prompt, output contract, or reasoning order.
+- General restructure: reorganizes the selected component, output contract, or reasoning order.
 - Over-correction risk: may improve one cluster while hurting another.
 
-When the reflection model added the same rules you were about to hand-write, do not hand-edit the seed just to feel useful. If GEPA can see and fix the failure from train examples, the next move is usually more budget, better feedback, or better data, not manual prompt patching. Hand-edit only when the optimizer cannot see the failure mode, such as zero train examples for that category.
+When the reflection model added the same rules you were about to write, do not directly edit the seed component just to feel useful. If GEPA can see and fix the failure from train examples, the next move is usually more budget, better feedback, or better data, not an unmeasured component patch. When the optimizer cannot see the failure mode, such as zero train examples for that category, update the selected component in the complete instruction-set manifest, then hand that manifest and the exact push command to a human curator:
+
+```bash
+# Human/local CLI only: a human curator with a user token runs this mutation.
+orizu instructions push <manifest> --project <team/project> --set <slug-or-exact-name> --json
+```
 
 ### 3. Per-Row Outcome Decomposition
 
@@ -72,7 +77,7 @@ Decompose validation or held-out outcomes:
 - Persistent failures: wrong before and after. Classify each as one of:
   - Data gap: failure mode underrepresented or absent in train.
   - Contested gold: label or rationale appears questionable and needs human re-review.
-  - Beyond prompt scope: the failure needs tools, state, retrieval, or reasoning outside this prompt.
+  - Beyond instruction scope: the failure needs tools, state, retrieval, or reasoning outside this instruction set.
   - Calibration overshoot: instructions pushed too far in one direction.
 
 For judge optimization, include flag/ok recall and precision alongside the confusion matrix. A jump in rare-class recall can be more important than a modest kappa movement.
@@ -82,7 +87,7 @@ For judge optimization, include flag/ok recall and precision alongside the confu
 Report:
 - Pareto frontier size. A frontier of 1 or 2 means limited parent diversity.
 - Acceptance rate by iteration. Many rejections suggest reflection is exploring but not finding hills; many acceptances suggest it is climbing a real signal.
-- Budget state. If budget was exhausted, the run paused before auto-promotion; manually decide whether to promote/finish. If max iterations was reached with budget remaining, the run likely converged under the configured search.
+- Budget state. If budget was exhausted, the run paused before auto-promotion; the coding agent may finish the run. The human-only action is moving the production pointer with `optimizations promote --label production`. If max iterations was reached with budget remaining, the run likely converged under the configured search.
 - `scoreOverTime` / validation trajectory. Still climbing at the end suggests raising budget or iterations. Plateaued curves point toward scorer, feedback, or data work upstream.
 - Reflection model, inference model, scorer model, provider settings, minibatch size, resolved thread count, budget preset/limit, candidate selection strategy, seed, and cache settings.
 
@@ -103,7 +108,7 @@ Common recommendations:
 ### 6. What Not To Do
 
 List unsupported moves so the next agent does not burn cycles. Examples:
-- Do not hand-edit the prompt when the best candidate already learned the intended failure rules.
+- Do not directly edit the selected component when the best candidate already learned the intended failure rules.
 - Do not raise budget when score over time plateaued and persistent failures are data/gold issues.
 - Do not switch metrics because one small validation result looks noisy; first measure variance across repeated runs or larger samples.
 - Do not optimize against a scorer whose feedback is too generic for reflection to learn from.
@@ -113,7 +118,7 @@ List unsupported moves so the next agent does not burn cycles. Examples:
 End with:
 - Run id and dashboard link.
 - Local log path or export artifact path.
-- Prompt/scorer/runner/optimizer version ids.
+- Instruction-set profile, scorer, runner, and optimizer version ids.
 - Dataset version id, split set id, train/validation split names, row counts, and random seed.
 - Commands used to start/export/finish the run, with secrets omitted.
 - Links to relevant skill sections, especially `optimization-with-gepa.md`, `prompt-control-plane.md`, `building-judges.md`, and this report guide.
@@ -132,7 +137,7 @@ Set an explicit expectation before the run: for example, "if best kappa does not
 
 Default budget presets are DSPy-style metric-call budgets. `light`, `medium`, and `heavy` map to DSPy's `auto="light"`, `auto="medium"`, and `auto="heavy"` scales; `auto` is treated as the balanced `medium` preset and is the default when no budget control is provided. The final metric-call limit scales with validation-set size, rather than using fixed tiny constants. `--budget`, `--max-metric-calls`, `--max-full-evals`, `--max-iterations`, and `--max-candidate-proposals` are mutually exclusive CLI budget controls; choose only one. The proposal cap is available only on the official engine.
 
-Metric-call and full-eval budgets are checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. If auto-promotion matters, choose a single budget control large enough to cover the intended search.
+Metric-call and full-eval budgets are checked only between iterations. Once an iteration starts, `run-gepa` completes the parent minibatch, child minibatch, and full validation eval for an accepted child even if that overshoots the nominal budget. If a run ends as `budget_exhausted`, it pauses and does not auto-promote. Auto-promotion is human-only; coding agents must not size or configure a run to trigger it, and instead hand validated candidates to a human curator for an explicit decision.
 
 ### Reflection Signal Quality