Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
feat(skillopt): deprecate the iterative loop (skillopt_loop_deprecated notice; removal on or after 2026-12-03)
garrytanee1bf546e09f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 892596bbc4..049d0a247c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Originaidentifiers and attribution are available in the pre-removal Git revision`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).+## [Unreleased]++**SkillOpt's iterative loop is deprecated and will be removed on or after 2026-12-03.** The loop tied a single rewrite on gbrain-evals' benchmarks at about 1.8 times the cost, and every edit it kept came from its first step, so it is being retired. `gbrain skillopt --loop`, a `--resume` of a run the loop started, `run_skillopt` with `optimizer_mode: "reflect"` and a queued `skillopt` job in loop mode now print the `skillopt_loop_deprecated` coaching notice once (over MCP, once per session) and otherwise run exactly as before. Nothing replaces the loop: edit the skill directly, or run the default one-shot rewrite, which stays. Nothing is removed and no default changes in this release.++### Itemized changes++- `src/core/skillopt/loop-deprecation.ts` (new): the notice text, the removal date and the one emitter, called by `gbrain skillopt` (after it resolves the mode, so a resumed loop run counts), the `run_skillopt` op (`ctx.emitNotice`, so MCP and `gbrain call` render it) and the `skillopt` job handler. `skillopt_loop_deprecated` is a new coaching code in `NOTICE_CODES`.+- `gbrain skillopt --help`, the `run_skillopt` description and its `optimizer_mode` parameter, docs/guides/skillopt.md, the tutorial and the `skill-optimizer` skill mark the loop deprecated.+- `test/skillopt/loop-deprecation.serial.test.ts`: each entry point that runs the loop emits the notice exactly once and still runs it; the one-shot default, a one-shot job and the cycle phase emit none.+## [0.60.565.0] - 2026-11-03**The per-file index describes how pages stored in segments are written and held.** The key-files entries for `write-through.ts` and `sync-entry-fault.ts` contradicted v0.60.560.0: the first said every page is rendered whole and `content` always holds the bytes written, and the second said a page-body fault at the freeze stops the run. They now describe the streamed write of a segmented page (measured at its snapshot's revision, checked against the scan cap before `source_path` binds, `inlineOnly` and `segmented_page`) and the `page_write_failed` hold that names `page_body_segmented` or `page_body_rows_unreadable`. The entries for full sync, `sync status`, the derived write-through and export also name `reexport_failures`, `last_error.request_id: null`, the `freeze_page_body_*` routing, the derived writer's `segmented_page` skip and the export's revision pin. Docs only.diff --git a/docs/TOOL_CATALOG.md b/docs/TOOL_CATALOG.mdindex c413db0f40..88910c6894 100644--- a/docs/TOOL_CATALOG.md+++ b/docs/TOOL_CATALOG.md@@ -20,7 +20,7 @@ Every non-localOnly operation on the MCP surface: 164 tools across 25 areas. **S| `quarantine_list` | List quarantined (hidden) and optionally content-flagged pages by scanning page frontmatter, newest-updated first. | admin | | || `run_doctor` | Run brain health checks and return a structured DoctorReport (thin-client doctor surface). | admin | | || `run_onboard` | Probe brain health + optionally submit onboard remediations. | admin | | |-| `run_skillopt` | Run SkillOpt against a single skill. | admin | | |+| `run_skillopt` | Run SkillOpt against a single skill; its iterative loop (optimizer_mode "reflect") is deprecated and removed on or after 2026-12-03. | admin | | |## advisordiff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.mdindex 5cd34d0f92..61ce77845a 100644--- a/docs/architecture/key-files/skills.md+++ b/docs/architecture/key-files/skills.md@@ -25,7 +25,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/skill-trigger-index.ts` — Shared loader that unions per-skill SKILL.md frontmatter `triggers:` with curated RESOLVER.md / AGENTS.md rows from `skillsDir` AND the parent dir (preserves the OpenClaw workspace-root layout). UNION semantics: explicit RESOLVER.md rows ADD to frontmatter triggers (don't replace). Dedup keyed on `(skillPath, trigger.trim().toLowerCase())`. Three consumers fold through this primitive — `checkResolvable`, `runRoutingEvalCli`, `mounts-cache.composeResolvers` — so fixing frontmatter reaches all of them. Exports `loadSkillTriggerIndex(skillsDir): SkillTriggerEntry[]`, `entriesToResolverContent(entries): string` (synthesizes a markdown-table resolver string for `runRoutingEval`'s string-content API), `findPrimaryResolverPath(skillsDir): string | null`, the `FRONTMATTER_SECTION` constant, and `_resetWarnedSkillsForTests`. Skip rules: non-directory entries (a symlink dirent is followed via `statSync` — `readdirSync` dirents report the link's OWN type without following, so skill dirs symlinked in from a shared store, e.g. `~/.agents/skills/<name>`, still load), `_*`/`.*` prefixes, `conventions/`+`migrations/` subdirs, skills with no `SKILL.md` (deprecated `install/` graceful-skipped), no `triggers:` array, or malformed YAML (warn-once + skip). Reuses `parseSkillFrontmatter` from `src/core/skill-frontmatter.ts`, including block and wrapped flow-sequence arrays. Pinned by `test/skill-trigger-index.test.ts` (18 hermetic cases). CI gate `bun run check:resolver` (= `bun src/cli.ts check-resolvable --strict --skills-dir skills/`) wired into `bun run verify`.-- `src/core/skillopt/` + `src/commands/skillopt.ts` + `skills/skill-optimizer/` — self-evolving skill optimization grounded in the SkillOpt paper (arXiv 2605.23904). `gbrain skillopt <skill>` treats `SKILL.md` as trainable parameters of a frozen agent: validation-gated (median-of-3 + epsilon=0.05), budget-capped (preflight estimator), per-skill DB-locked (`tryAcquireDbLock('skillopt:<name>', 60min)`), atomic-versioned (history-intent-first 5-step commit), body-only mutations (frontmatter forbidden). Rollouts use `gateway.toolLoop` directly with no-op persistence callbacks (zero `subagent_messages` pollution) + a read-only tool allowlist derived from `BRAIN_TOOL_ALLOWLIST` minus `put_page`/`submit_job`/`file_upload`. Default is one gated one-shot rewrite (`optimizerMode`); `--loop` runs two reflect calls per step; rejected-edit buffer LRU-bounded to 100; bundled-skill gate; bootstrap workflow (sentinel + `--bootstrap-reviewed`); D_sel floor (>=5 with `--split` override); audit JSONL via `audit-writer.ts`. Added to `ALL_PHASES` after `patterns` (default OFF; opt-in via `gbrain config set cycle.skillopt.enabled true`); cycle phase wrapper at `src/core/skillopt/cycle-phase.ts` walks stale skills with per-skill ($0.50) + brain-wide ($2.00) caps. Added to `PROTECTED_JOB_NAMES`. Surface: dream-cycle phase wrapper; `--all` batch mode (`src/core/skillopt/batch.ts:runBatchAll`); `--target-models` fleet (`runFleet` parallel per-model receipts under `skillopt/fleet/<slug>/`); MCP op `run_skillopt` (admin scope + per-skill `skillopt.allowed_skills` allowlist, NOT localOnly, validates `skill_name` kebab-only + confines caller-supplied benchmark/held-out paths to skillsDir for remote callers); Minion `skillopt` handler + `--background` with `allowProtectedSubmit: true`; write-flavored optimization via `src/core/skillopt/write-capture.ts:buildWriteCaptureRegistry` (virtual `put_page`/`submit_job`/`file_upload` captured in-memory; `--write-capture` flag; its read tools and the rollout registry in `rollout.ts` drop `""`/`null` optional arguments and validate against the op schema before the handler, like MCP dispatch, and throw a failed read as `asAgentToolError` (`src/mcp/dispatch.ts`) so the model reads the same code, message, suggestion and runnable `fix` a read-scope HTTP MCP caller gets, with a fix naming only tools the rollout offers); held-out real-user test set via `src/core/skillopt/held-out.ts` (capture infra at `~/.gbrain/skillopt-captures/<skill>/<run>.jsonl`, `--held-out <path>` flag, `runHeldOutGate` candidate >= baseline). Hermetic via DI seams (`opts.chatFn` for optimizer + judge; `opts.toolLoopFn` for rollouts; no `mock.module`). `--bootstrap-from-skill` → `runBootstrapFromSkill` in `src/core/skillopt/bootstrap-benchmark.ts`: reads `SKILL.md` directly (no `routing-eval.jsonl`), makes ONE LLM call emitting a full starter benchmark (tasks + rule judges) as JSONL, parsed line-by-line with skip-bad-line salvage and a min-2-valid-checks-per-task drop; provider/transport errors PROPAGATE (not collapsed to `bootstrap_empty`). `--bootstrap-tasks N` (default 15, capped 50); `maxTokens` scales `min(8000, max(4000, N*220))`. The stderr REVIEW line prints the literal `gbrain skillopt <name> --bootstrap-reviewed --split 1:1:1` — load-bearing because the default `4:1:5` split makes a 15-task starter's `D_sel = floor(15/10) = 1`, below the `>=5` floor, so a 15-task benchmark needs `--split 1:1:1`. Both bootstrap generators share `assertBenchmarkAbsent` + `readSkillBodyOrThrow`; `--bootstrap-from-skill` is mutually exclusive with `--bootstrap-from-routing`/`--benchmark`/`--all`/`--target-models`/`--resume`. Generated rule judges are explicitly WEAK DRAFTS to be strengthened during the review gate. The held-out gate is wired: `--held-out <path>` is parsed and threaded through every caller (CLI main + `--background` `held_out_path` + batch/fleet `heldOutPath` + the `run_skillopt` `held_out_path` param), running at CHECKPOINT ACCEPTANCE so no-mutate/fleet paths can't promote a held-out-failing candidate. `assertBundledMutationHeldOut` in bundled-skill-gate.ts: bundled + `--allow-mutate-bundled` requires a NON-EMPTY held-out (`MIN_HELD_OUT_SIZE = D_SEL_MIN_SIZE` = 5, derived so they can't desync) or hard-refuses (exit 2), for ALL callers (they funnel through `runSkillOpt`); held-out must be task_id-DISJOINT from the benchmark (overlap rejected — can't catch overfitting). `receipt.baseline_sel_score` populated + a real final-test eval (`test_score` + `baseline_test_score`) scoring best + baseline on `split.test`; shared `scoreSkillOnTasks` primitive (validate-gate.ts) backs baseline/final-test/held-out scoring. `--no-mutate` writes proposed.md via `writeProposed` in version-store.ts. `maxRuntimeMin` ENFORCED (wall-clock deadline between steps → `skillopt_runtime_exceeded` → outcome aborted). Two eval-internal ablation opts on `SkillOptOpts` (NOT on CLI): `reflectMode` (`'both'`/`'failure-only'`) and `disableValidationGate` (greedy-accept), recorded in `RunReceipt` + audit `run_start` for replayability; `optimizerMode` is a product setting, required on `SkillOptOpts` (`'one-shot-rewrite'` default, `'reflect'` = `--loop`; `optimizer_mode` on the `run_skillopt` op and job data) and recorded in the receipt; `ROLLOUT_SUCCESS_THRESHOLD = 0.5` named constant for the partition; one-shot fence-strip is anchored (`^```...```$`) so an embedded code sample isn't truncated. Claude Haiku 4.5's dateless canonical id `claude-haiku-4-5` is in `src/core/anthropic-pricing.ts` (a `BudgetTracker`-capped run on Haiku would otherwise throw `no_pricing` on the FIRST `chat()` of every rollout); `runValidationGate` (validate-gate.ts) scans settled results for `isMustAbortError(error)` (from `worker-pool.ts`; `BUDGET_EXHAUSTED` is in `MUST_ABORT_ERROR_TAGS`) and re-throws so the caller aborts loudly instead of recording a hollow `selScore:0` — ordinary non-abort rollout errors still fail-open to `score:0` (judge-hiccup posture preserved), but a 100%-failed gate (every task errored — e.g. a logged-out `claude-cli` child — or every rollout carrying a `judge_error`) throws `skillopt_all_rollouts_failed` / `skillopt_all_judge_errors` (constants exported from validate-gate.ts) so a dead provider ends the run `errored` with the first provider message as `abort_detail` instead of a plausible `no_improvement` at 0.000; the orchestrator's zero-candidate step (reflect produced/parsed no edits) logs audit reason `no_edits_proposed[: <first reflect error>]` + one stderr line, distinct from the apply-rejected `no_edits_applied`, and does not touch the rejected buffer. `GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG=1` (empty config dir) logs the child out on every platform, macOS included — docs/comment make no keychain-survives claim (pinned by `test/skillopt/deadline-and-hermetic.test.ts`). Pinned by 152 tests across 18 files (foundation + adversarial + v2 surface + E2E PGLite serial), `test/skillopt/bootstrap-from-skill.test.ts` (20 cases), `test/skillopt/rollout.test.ts`, `test/skillopt/validate-gate-abort.test.ts` (7 cases), held-out ENFORCE + one-shot-rewrite unit cases, and e2e (held-out block/allow, bundled no-mutate, runtime deadline, receipt honesty, held-out disjointness, no-DB-pollution). Drives the Track B SkillOpt benchmark suite in the sibling `gbrain-evals` repo.+- `src/core/skillopt/` + `src/commands/skillopt.ts` + `skills/skill-optimizer/` — self-evolving skill optimization grounded in the SkillOpt paper (arXiv 2605.23904). `gbrain skillopt <skill>` treats `SKILL.md` as trainable parameters of a frozen agent: validation-gated (median-of-3 + epsilon=0.05), budget-capped (preflight estimator), per-skill DB-locked (`tryAcquireDbLock('skillopt:<name>', 60min)`), atomic-versioned (history-intent-first 5-step commit), body-only mutations (frontmatter forbidden). Rollouts use `gateway.toolLoop` directly with no-op persistence callbacks (zero `subagent_messages` pollution) + a read-only tool allowlist derived from `BRAIN_TOOL_ALLOWLIST` minus `put_page`/`submit_job`/`file_upload`. Default is one gated one-shot rewrite (`optimizerMode`); `--loop` runs two reflect calls per step (deprecated, removed on or after 2026-12-03: `loop-deprecation.ts` emits the `skillopt_loop_deprecated` coaching notice once per CLI run, `run_skillopt` call and job that runs the loop; `test/skillopt/loop-deprecation.serial.test.ts`); rejected-edit buffer LRU-bounded to 100; bundled-skill gate; bootstrap workflow (sentinel + `--bootstrap-reviewed`); D_sel floor (>=5 with `--split` override); audit JSONL via `audit-writer.ts`. Added to `ALL_PHASES` after `patterns` (default OFF; opt-in via `gbrain config set cycle.skillopt.enabled true`); cycle phase wrapper at `src/core/skillopt/cycle-phase.ts` walks stale skills with per-skill ($0.50) + brain-wide ($2.00) caps. Added to `PROTECTED_JOB_NAMES`. Surface: dream-cycle phase wrapper; `--all` batch mode (`src/core/skillopt/batch.ts:runBatchAll`); `--target-models` fleet (`runFleet` parallel per-model receipts under `skillopt/fleet/<slug>/`); MCP op `run_skillopt` (admin scope + per-skill `skillopt.allowed_skills` allowlist, NOT localOnly, validates `skill_name` kebab-only + confines caller-supplied benchmark/held-out paths to skillsDir for remote callers); Minion `skillopt` handler + `--background` with `allowProtectedSubmit: true`; write-flavored optimization via `src/core/skillopt/write-capture.ts:buildWriteCaptureRegistry` (virtual `put_page`/`submit_job`/`file_upload` captured in-memory; `--write-capture` flag; its read tools and the rollout registry in `rollout.ts` drop `""`/`null` optional arguments and validate against the op schema before the handler, like MCP dispatch, and throw a failed read as `asAgentToolError` (`src/mcp/dispatch.ts`) so the model reads the same code, message, suggestion and runnable `fix` a read-scope HTTP MCP caller gets, with a fix naming only tools the rollout offers); held-out real-user test set via `src/core/skillopt/held-out.ts` (capture infra at `~/.gbrain/skillopt-captures/<skill>/<run>.jsonl`, `--held-out <path>` flag, `runHeldOutGate` candidate >= baseline). Hermetic via DI seams (`opts.chatFn` for optimizer + judge; `opts.toolLoopFn` for rollouts; no `mock.module`). `--bootstrap-from-skill` → `runBootstrapFromSkill` in `src/core/skillopt/bootstrap-benchmark.ts`: reads `SKILL.md` directly (no `routing-eval.jsonl`), makes ONE LLM call emitting a full starter benchmark (tasks + rule judges) as JSONL, parsed line-by-line with skip-bad-line salvage and a min-2-valid-checks-per-task drop; provider/transport errors PROPAGATE (not collapsed to `bootstrap_empty`). `--bootstrap-tasks N` (default 15, capped 50); `maxTokens` scales `min(8000, max(4000, N*220))`. The stderr REVIEW line prints the literal `gbrain skillopt <name> --bootstrap-reviewed --split 1:1:1` — load-bearing because the default `4:1:5` split makes a 15-task starter's `D_sel = floor(15/10) = 1`, below the `>=5` floor, so a 15-task benchmark needs `--split 1:1:1`. Both bootstrap generators share `assertBenchmarkAbsent` + `readSkillBodyOrThrow`; `--bootstrap-from-skill` is mutually exclusive with `--bootstrap-from-routing`/`--benchmark`/`--all`/`--target-models`/`--resume`. Generated rule judges are explicitly WEAK DRAFTS to be strengthened during the review gate. The held-out gate is wired: `--held-out <path>` is parsed and threaded through every caller (CLI main + `--background` `held_out_path` + batch/fleet `heldOutPath` + the `run_skillopt` `held_out_path` param), running at CHECKPOINT ACCEPTANCE so no-mutate/fleet paths can't promote a held-out-failing candidate. `assertBundledMutationHeldOut` in bundled-skill-gate.ts: bundled + `--allow-mutate-bundled` requires a NON-EMPTY held-out (`MIN_HELD_OUT_SIZE = D_SEL_MIN_SIZE` = 5, derived so they can't desync) or hard-refuses (exit 2), for ALL callers (they funnel through `runSkillOpt`); held-out must be task_id-DISJOINT from the benchmark (overlap rejected — can't catch overfitting). `receipt.baseline_sel_score` populated + a real final-test eval (`test_score` + `baseline_test_score`) scoring best + baseline on `split.test`; shared `scoreSkillOnTasks` primitive (validate-gate.ts) backs baseline/final-test/held-out scoring. `--no-mutate` writes proposed.md via `writeProposed` in version-store.ts. `maxRuntimeMin` ENFORCED (wall-clock deadline between steps → `skillopt_runtime_exceeded` → outcome aborted). Two eval-internal ablation opts on `SkillOptOpts` (NOT on CLI): `reflectMode` (`'both'`/`'failure-only'`) and `disableValidationGate` (greedy-accept), recorded in `RunReceipt` + audit `run_start` for replayability; `optimizerMode` is a product setting, required on `SkillOptOpts` (`'one-shot-rewrite'` default, `'reflect'` = `--loop`; `optimizer_mode` on the `run_skillopt` op and job data) and recorded in the receipt; `ROLLOUT_SUCCESS_THRESHOLD = 0.5` named constant for the partition; one-shot fence-strip is anchored (`^```...```$`) so an embedded code sample isn't truncated. Claude Haiku 4.5's dateless canonical id `claude-haiku-4-5` is in `src/core/anthropic-pricing.ts` (a `BudgetTracker`-capped run on Haiku would otherwise throw `no_pricing` on the FIRST `chat()` of every rollout); `runValidationGate` (validate-gate.ts) scans settled results for `isMustAbortError(error)` (from `worker-pool.ts`; `BUDGET_EXHAUSTED` is in `MUST_ABORT_ERROR_TAGS`) and re-throws so the caller aborts loudly instead of recording a hollow `selScore:0` — ordinary non-abort rollout errors still fail-open to `score:0` (judge-hiccup posture preserved), but a 100%-failed gate (every task errored — e.g. a logged-out `claude-cli` child — or every rollout carrying a `judge_error`) throws `skillopt_all_rollouts_failed` / `skillopt_all_judge_errors` (constants exported from validate-gate.ts) so a dead provider ends the run `errored` with the first provider message as `abort_detail` instead of a plausible `no_improvement` at 0.000; the orchestrator's zero-candidate step (reflect produced/parsed no edits) logs audit reason `no_edits_proposed[: <first reflect error>]` + one stderr line, distinct from the apply-rejected `no_edits_applied`, and does not touch the rejected buffer. `GBRAIN_CLAUDE_CLI_HERMETIC_CONFIG=1` (empty config dir) logs the child out on every platform, macOS included — docs/comment make no keychain-survives claim (pinned by `test/skillopt/deadline-and-hermetic.test.ts`). Pinned by 152 tests across 18 files (foundation + adversarial + v2 surface + E2E PGLite serial), `test/skillopt/bootstrap-from-skill.test.ts` (20 cases), `test/skillopt/rollout.test.ts`, `test/skillopt/validate-gate-abort.test.ts` (7 cases), held-out ENFORCE + one-shot-rewrite unit cases, and e2e (held-out block/allow, bundled no-mutate, runtime deadline, receipt honesty, held-out disjointness, no-DB-pollution). Drives the Track B SkillOpt benchmark suite in the sibling `gbrain-evals` repo.- `src/core/skillopt/{reflect,output-cap,run-outcome,remediation,checkpoint,models-plan,job,bootstrap-run,must-abort,preflight}.ts` — skillopt run honesty and model provenance (user docs: `docs/guides/skillopt.md` "Optimizer output" + "Model provenance"). **Output caps** (`output-cap.ts`): one optimizer cap for every reflect call (patch + rewrite modes) and the default one-shot rewrite, precedence `--reflect-max-tokens` / MCP+job `reflect_max_tokens` (remote callers clamped to 256-32000) > `skillopt.reflect_max_tokens` (invalid warns once, valid honored exactly) > `defaultMaxOutputTokens(optimizer)` (32000 thinking, 4096 otherwise); `skilloptOutputCap(model, siteCap)` gives the judge (200) and bootstrap sites `max(siteCap, 8192)` on thinking models only — gateway `chat()` semantics are untouched. **Reply classification** (`reflect.ts`): at most one error per call, in precedence `reflect_<mode>_truncated` (length stop; partial edits dropped) > `_empty_reply` > `_no_parseable_edits` > `_invalid_edits`; a fenced or bare `{"edits": []}` is a deliberate, usable empty; partial invalid drops sum into `reflect_invalid_edits_dropped`; the skill body is sent whole when it fits `resolveChatContextTokens(optimizer)` minus output cap and bounded prompt overhead at 3 chars/token (unknown window → 120,000 chars), else truncated with an in-prompt disclosure + `skill_body_truncated`; prompt + cap over the window refuses the call (`_context_too_small`), provider length errors map to `_context_overflow`; the one-shot rewrite refuses on `one_shot_rewrite_output_cap_too_small` / `_body_truncated` and never promotes a `_truncated` reply. The judge records `judge_error: llm_truncated` and bootstrap rows skip as `truncated` on a length stop. **Must-abort** (`must-abort.ts`): budget exhaustion, AI spend-policy refusals, runtime deadline and SIGINT rethrow (the validation gate uses the same predicate) at every optimizer/judge/held-out/bootstrap site, so the run ends `aborted` with its real reason. **Outcome** (`run-outcome.ts`): `accepted` if any candidate was accepted (even after an early stop), `errored` with `abort_detail: optimizer_output_unusable: <first error>` when no optimizer reply in the whole run was usable, else `no_improvement`; 2 consecutive fully-unusable steps (any class) stop the loop (`stop_reason: early_stop_unusable_output`); `buildResumeCommand` rebuilds the exact resume command from the stored run spec plus the run's mode, cost cap, runtime cap, `--models-strict` and `--force` (only when the run used it; the dirty-tree gate admits a resume whose SKILL.md equals the checkpoint's best text); output-cap failures (from `abort_detail`, or the trailing reflect error of an early stop) double the reflect cap, contract failures put a quoted `'<other-model>'` in place of the optimizer model. An early-stopped run keeps its checkpoint and resume command even when it resolves `no_improvement`; a resume re-runs the trailing fully-unusable steps (`rewindCursor`) and restarts the early-stop streak, a kept checkpoint banks the final evaluation's spend and the rewound cursor is persisted before any save, the cycle's skillopt phase GCs kept checkpoints older than 7 days, and a legacy checkpoint whose best text moved past its baseline counts as already accepted. CLI exit map: accepted 0, no_improvement 1, aborted/errored 2. **Remediation** (`remediation.ts`): `SKILLOPT_REMEDIATION_CODES` → `{code, fix, docs}` receipt entries whose `docs` anchors into the guide's error-code table (pinned by `test/skillopt/error-code-docs.test.ts`); errors deduped, max 20 x 300 chars. **Checkpoint/resume** (`checkpoint.ts`): stores a `next_epoch`/`next_step` cursor (legacy checkpoints converted), the early-stop counter, the reflect tally, ledger rows and cost on completed steps and handled aborts (an abort saves the step-start tally, since resume re-runs that step), and a run spec; `--resume` refuses a changed benchmark/held-out/split or a no-mutate → mutate widening, and allows optimizer model, reflect cap and cost cap overrides; the receipt merges prior segments into `models_used` (`models_used_scope: full_run`, or `since_resume` for legacy checkpoints) plus `prior_segments_cost_usd`. **Models plan** (`models-plan.ts`): `resolveSkillOptModels` is the ONE role resolution (optimizer→tier deep, target→subagent, judge→reasoning; flag > config chain) used by the CLI, the `run_skillopt` op, the cycle phase and the job handler (four-path golden test); `buildModelsPlan` adds per-task judge overrides (benchmark + held-out; the default judge is inactive when no reachable LLM-judged task lacks its own `judge.model`), gateway expansion/chat with retained sources, the embedding model of the column search actually reads (file plane / `GBRAIN_EMBEDDING_MODEL`, never DB rows) and the reranker when enabled; the stderr banner prints before any spend and `models_plan` lands on the receipt + `run_start` audit. Strict mode (`--models-strict` / `skillopt.models_strict`; unrecognized values warn and count as on) aborts before spend when any active touchpoint came from `models_default`, `tier_default`, `fallback`, `unknown` or a capability substitution, listing a copy-paste fix per touchpoint (an unreadable `skillopt.models_strict` counts as on; an explicit `embedding_columns.embedding` override counts as configuration); it applies to batch, fleet, both bootstrap modes and background jobs. Echoed strings pass `sanitizeEcho` (control chars stripped, 200-char cap). **Jobs** (`job.ts`): job data records the model flags and strict setting; the handler re-resolves sources and re-runs the strict check at execution time, legacy jobs resolve as `unknown`. **Bootstrap** (`bootstrap-run.ts`): both bootstrap modes resolve the optimizer via the plan, print its banner row, honor strict and `--dry-run`, and run under a `--max-cost-usd` tracker. **Preflight** (`preflight.ts`): prices each role's per-call reservation with the tracker's `reservationCostUsd` at effective caps and aborts pre-spend with `reservation_exceeds_cap` naming the role; the heuristic expected-cost estimate is reported separately. The cycle phase forwards `abort_reason`/`abort_detail`/`run_id`/`remediation`, records `skipped_budget` (no calls; retried only after the admission fingerprint — optimizer/target/judge models, reflect cap, per-skill cap, `pricing.overrides`, gbrain version, benchmark content (unreadable benchmark re-admits) — changes) and gates `errored` retries 24h via `cycle.skillopt.last_error.<skill>` without banking `last_run`.diff --git a/docs/guides/skillopt.md b/docs/guides/skillopt.mdindex 576449d248..09f2c012c1 100644--- a/docs/guides/skillopt.md+++ b/docs/guides/skillopt.md@@ -8,6 +8,14 @@ that measurably improve the score.Based on [SkillOpt](https://arxiv.org/abs/2605.23904) (Microsoft Research,May 2026).+> **Deprecated: the iterative loop.** `--loop`, `run_skillopt`'s+> `optimizer_mode: "reflect"`, a `--resume` of a run the loop started and a+> queued `skillopt` job in loop mode are deprecated and will be removed on or+> after 2026-12-03. Each use prints the `skillopt_loop_deprecated` notice once+> (MCP: once per session) and otherwise runs exactly as before. Nothing+> replaces the loop: edit the skill directly, or run the default+> [one-shot rewrite](#one-shot-rewrite-the-default), which stays.+> **New to this?** Start with the hands-on tutorial:> [Auto-improve a skill with `gbrain skillopt`](../tutorials/improving-skills-with-skillopt.md).> It walks you from "I have a skill" to "I accepted a measurably better version"@@ -70,7 +78,10 @@ much. Every edit the loop kept came at its first step. `--loop` (MCP and jobreversible: it flips back if gbrain-evals' SkillOpt method benchmark shows theloop winning. A resume continues in the mode its run started in.-## How the loop works (`--loop`)+## How the loop works (`--loop`, deprecated)++Deprecated: removed on or after 2026-12-03 (see the banner at the top).+For each step:@@ -108,7 +119,7 @@ the audit event only; the full meta-edit proposal is a tracked follow-up.| `--judge-model MODEL` | tier.reasoning | Scores rollouts || `--reflect-max-tokens N` | `skillopt.reflect_max_tokens`, else 32000 (thinking optimizer) / 4096 | Output cap for every optimizer call. See [Optimizer output cap](#optimizer-output-cap) || `--models-strict` | `skillopt.models_strict`, else off | Abort before any spend unless every active model was explicitly configured. See [Strict mode](#strict-mode) |-| `--loop` | off | Run the iterative reflect loop instead of the default one gated rewrite. See [One-shot rewrite](#one-shot-rewrite-the-default) |+| `--loop` | off | Deprecated (removed on or after 2026-12-03). Run the iterative reflect loop instead of the default one gated rewrite. See [One-shot rewrite](#one-shot-rewrite-the-default) || `--dry-run` | off | Models banner, strict verdict and cost preview; zero model calls || `--no-mutate` | off | Write proposed.md, don't replace SKILL.md (no held-out needed) || `--allow-mutate-bundled` | off | Required to mutate gbrain-bundled skills in place — ALSO requires `--held-out` (>=5 rows) or the run hard-refuses |diff --git a/docs/tutorials/improving-skills-with-skillopt.md b/docs/tutorials/improving-skills-with-skillopt.mdindex e62933ad20..a5a3cb91f5 100644--- a/docs/tutorials/improving-skills-with-skillopt.md+++ b/docs/tutorials/improving-skills-with-skillopt.md@@ -183,7 +183,8 @@ You'll watch it work: a baseline eval to set the bar, one forward pass over abatch of train tasks (run the skill), one rewrite of the skill body from thoserollouts, and a validation gate that runs each sel task's judge 3 times andtakes the median — accepting only if the median beats the baseline by more than-0.05. (`--loop` runs the older iterative edit loop instead; see the+0.05. (`--loop` runs the older iterative edit loop instead. It is deprecated+and removed on or after 2026-12-03; see the[reference guide](../guides/skillopt.md#one-shot-rewrite-the-default).)When it finishes, the last lines tell you everything:diff --git a/plugin/skills/skill-optimizer/SKILL.md b/plugin/skills/skill-optimizer/SKILL.mdindex 2827e7dfc7..afd7c644ec 100644--- a/plugin/skills/skill-optimizer/SKILL.md+++ b/plugin/skills/skill-optimizer/SKILL.md@@ -60,7 +60,7 @@ gbrain skillopt <skill-name> [flags]│├── default: one rewrite of the body from a D_train forward pass,│ accepted only through the same D12 validation gate- ├── --loop (opt-in; has not beaten one-shot on benchmarks): for epoch in 1..N:+ ├── --loop (deprecated, removed on or after 2026-12-03): for epoch in 1..N:│ for step in 1..steps_per_epoch:│ ├── forward pass: rollouts on D_train batch│ ├── backward pass: reflect × 2 (failures + successes per D7)@@ -147,7 +147,7 @@ https://github.com/garrytan/gbrain/blob/master/docs/tutorials/improving-skills-w| Bundled skill (skills/ in gbrain repo) | Default writes proposed.md; to commit in place add `--allow-mutate-bundled` AND `--held-out <path>` (>=5 benchmark-disjoint tasks) — else it hard-refuses. Plugin installs cannot mutate bundled skills in place (the snapshot is read-only): copy the SKILL.md into your own skills dir to iterate, or stick with the default proposed.md review flow || Want to review changes before applying | Add `--no-mutate` (writes proposed.md, no held-out needed) || Guard against benchmark overfitting | Add `--held-out <path>` — checked once on the final candidate; one that beats the benchmark but regresses on the held-out set is refused |-| Want the iterative edit loop | Add `--loop` (about 1.8x the cost; it tied one-shot on gbrain-evals Cat 31) |+| Want the iterative edit loop | Don't: `--loop` is deprecated and removed on or after 2026-12-03 (it prints `skillopt_loop_deprecated`). Run the default one-shot rewrite or edit the skill directly || Mid-run crash | `gbrain skillopt foo --resume <run-id>` |## Output Formatdiff --git a/scripts/serial-weights.json b/scripts/serial-weights.jsonindex 78fc99beb6..bf4e4ba592 100644--- a/scripts/serial-weights.json+++ b/scripts/serial-weights.json@@ -400,6 +400,7 @@"test/shared-skills-optimizer.serial.test.ts": 25,"test/shared-skills-restore.serial.test.ts": 27,"test/skillopt/cycle-phase-caps.serial.test.ts": 4,+ "test/skillopt/loop-deprecation.serial.test.ts": 3,"test/skillopt/models-four-paths.serial.test.ts": 4,"test/skillopt/models-plan.serial.test.ts": 3,"test/skillopt/run-skillopt-op.serial.test.ts": 3,diff --git a/skills/skill-optimizer/SKILL.md b/skills/skill-optimizer/SKILL.mdindex e5a22ae995..6f0378899e 100644--- a/skills/skill-optimizer/SKILL.md+++ b/skills/skill-optimizer/SKILL.md@@ -59,7 +59,7 @@ gbrain skillopt <skill-name> [flags]│├── default: one rewrite of the body from a D_train forward pass,│ accepted only through the same D12 validation gate- ├── --loop (opt-in; has not beaten one-shot on benchmarks): for epoch in 1..N:+ ├── --loop (deprecated, removed on or after 2026-12-03): for epoch in 1..N:│ for step in 1..steps_per_epoch:│ ├── forward pass: rollouts on D_train batch│ ├── backward pass: reflect × 2 (failures + successes per D7)@@ -146,7 +146,7 @@ https://github.com/garrytan/gbrain/blob/master/docs/tutorials/improving-skills-w| Bundled skill (skills/ in gbrain repo) | Default writes proposed.md; to commit in place add `--allow-mutate-bundled` AND `--held-out <path>` (>=5 benchmark-disjoint tasks) — else it hard-refuses. Plugin installs cannot mutate bundled skills in place (the snapshot is read-only): copy the SKILL.md into your own skills dir to iterate, or stick with the default proposed.md review flow || Want to review changes before applying | Add `--no-mutate` (writes proposed.md, no held-out needed) || Guard against benchmark overfitting | Add `--held-out <path>` — checked once on the final candidate; one that beats the benchmark but regresses on the held-out set is refused |-| Want the iterative edit loop | Add `--loop` (about 1.8x the cost; it tied one-shot on gbrain-evals Cat 31) |+| Want the iterative edit loop | Don't: `--loop` is deprecated and removed on or after 2026-12-03 (it prints `skillopt_loop_deprecated`). Run the default one-shot rewrite or edit the skill directly || Mid-run crash | `gbrain skillopt foo --resume <run-id>` |## Output Formatdiff --git a/skills/skills.lock.json b/skills/skills.lock.jsonindex c08b76dd16..ee9eac5b78 100644--- a/skills/skills.lock.json+++ b/skills/skills.lock.json@@ -216,7 +216,7 @@"skill-autobench/SKILL.md": "29f5760dcfd823c5f7d4fb50a3cf4e36601b1b8125e57d6bf83645a41f97f613","skill-autobench/routing-eval.jsonl": "8d961ed6403b7e2f690948e4c18529d40f26f6f21064befc56d465966b1a9ec0","skill-creator/SKILL.md": "ae8119e6a28faacdc48b13a51c89ff752e9d1b698a4ed0b49f380eb1de16e322",- "skill-optimizer/SKILL.md": "8f0dea0c50e180619f732841a5a23faee989506bab252a28b0fbd9aa13bf397f",+ "skill-optimizer/SKILL.md": "5a9ef81ba97200479bff7fa4965e1f5189cf323f0cc4aa42cec614274a544b09","skill-optimizer/routing-eval.jsonl": "48f7fc04414b194ee8674577c3e58e03ebd7f74d836766bd16cb5abfd4effb76","skill-optimizer/skillopt-benchmark.jsonl": "5552457d6eaa32486b79796d12fcbe2c078b0c53d7fbdaf582f0fd1a17e9a381","skillify/SKILL.md": "6fa84bd744b1082d6550def977b49ecaac7ada0abf1a04180a8e3b0d432fb20e",diff --git a/src/commands/skillopt.ts b/src/commands/skillopt.tsindex c8e54442cc..e6f337dcfa 100644--- a/src/commands/skillopt.ts+++ b/src/commands/skillopt.ts@@ -21,6 +21,7 @@ import {import { SKILLOPT_HELP_TEXT } from '../core/skillopt/help.ts';import { runSkillOpt, parseSplit } from '../core/skillopt/orchestrator.ts';import { checkpointOptimizerMode, checkpointPath, loadCheckpoint } from '../core/skillopt/checkpoint.ts';+import { noteSkillOptLoopDeprecated } from '../core/skillopt/loop-deprecation.ts';import { formatModelsUsedTable } from '../core/budget/models-used.ts';import { parsePositiveInt } from '../core/skillopt/output-cap.ts';import { serializeError, StructuredAgentError } from '../core/errors.ts';@@ -157,6 +158,7 @@ export async function runSkillOptCommand(engine: BrainEngine | null, args: strin// checkpoint ran (a checkpoint from before this default ran the loop).const resumed = parsed.resumeRunId && parsed.skillName ? loadCheckpoint(skillsDir, parsed.skillName, parsed.resumeRunId) : null;const optimizerMode: OptimizerMode = parsed.loop ? 'reflect' : resumed ? checkpointOptimizerMode(resumed) : 'one-shot-rewrite';+ noteSkillOptLoopDeprecated(optimizerMode);// ── F4: --all batch mode ────────────────────────────────────────────────if (parsed.all) {diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 25f3b1b596..618a42ec5b 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1420,6 +1420,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;// GBRA-200 (harness ask 6: stamp degraded replies). `since` is stamped at the merge slot.{ since: '0.60.563.0', id: 'write_grant_refusal_gbra200', text: 'A `remember` naming a `source_id` outside the connection\'s write grant is still refused `scope_denied` (a page write: `permission_denied`), and the refusal now carries `writable_source_ids`: the sources the connection\'s own grant lets it write, never another source, identical whether the named source exists or not. On `remember` the `fix` repeats the call against that source once the user agrees (`next: ask_user`, naming both sources), so a harness can retry instead of giving up; `forget`, `forget_fact` and page writes carry no fix.' },{ since: '0.60.563.0', id: 'degraded_stamp_gbra200', text: 'Every degraded or partial read result now carries one stamp naming why with stable codes: an MCP result gets `_meta.degraded: { reasons: [...] }` and one extra text block, `[gbrain degraded: <reasons>] ...`, after the others; a CLI `--json` object gets a `degraded` key, and other CLI output (human text, a bare `--json` array such as search results) gets that line on stderr. It covers search, query, recall, find_experts, context_pack, delta, entity, get_page (`file_held`), think and synthesize, search_exact, open_loops and rank_entities. recall and think no longer drop their page search\'s degraded stages (an embed timeout, a failed arm, the keyword rank bound): recall reports them in `_meta.retrieval.degraded` and its `degraded_recall` notice, think and synthesize as `GATHER_DEGRADED:<stage>` warnings, and a keyword-only search or recall on Postgres reports `keyword_candidates_incomplete` when the rank bound applies. A clean result carries no stamp, and no existing field changed.' },+ { since: 'TBD', id: 'skillopt_loop_deprecated_gst1251', text: 'SkillOpt\'s iterative loop is deprecated and is removed on or after 2026-12-03: `gbrain skillopt` with its loop flag, a resumed run the loop started, `run_skillopt` with `optimizer_mode: "reflect"` and a queued `skillopt` job in loop mode (including one queued before the one-shot default, which carries no mode) each print the `skillopt_loop_deprecated` coaching notice once (MCP: once per session, muteable) and otherwise run exactly as before. The default one-shot rewrite, the cycle phase and every flag and config key are unchanged. Nothing replaces the loop: edit the skill directly, or run the default one-shot rewrite.' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex 566633a0db..d59826f1b6 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -912,6 +912,7 @@ export const NOTICE_CODES = {migrations_pending: { kind: 'safety', summary: 'Schema migrations are pending or failed to apply on this brain.' },socket_identity_mismatch: { kind: 'degraded', summary: 'The running serve\'s warm CLI socket refused this CLI call because an identity part (named, never its value) differs from the serve\'s, so the call ran on the slower cold path; doctor `cli_socket_refusals` counts these.' },sync_retry_failed_deprecated: { kind: 'coaching', summary: '`gbrain sync --retry-failed` is a deprecated alias for a plain sync, accepted for two releases: a plain sync retries a failure the previous run recorded by itself. Drop the flag.' },+ skillopt_loop_deprecated: { kind: 'coaching', summary: 'SkillOpt\'s iterative loop (the skillopt loop flag, `run_skillopt` `optimizer_mode: "reflect"`, a resumed loop run or a queued loop job) is deprecated and is removed on or after 2026-12-03; the run continues unchanged. Nothing replaces it: edit the skill directly, or run the default one-shot rewrite.' },sync_tail_degraded: { kind: 'degraded', summary: 'A managed sync ended synced, but its post-checkpoint tail (planner statistics, link extraction for the imported pages) failed, was cut off at its budget or did not start before the run\'s deadline; the step stays scheduled for the next sync, and the fix runs it now (`gbrain extract --stale --source-id <id>`, or doctor for the statistics).' },no_resident: { kind: 'degraded', summary: 'gbrain sync trigger recorded the request (and queued a job or nudged the serve), but no resident (gbrain serve, gbrain jobs work or the autopilot daemon) watches the source, so the recorded request waits until one starts or a sync reaches it; the fix syncs the checkout HEAD now (`gbrain sync --source <id> --no-pull`). docs/guides/on-commit-sync.md#no-resident' },no_worker: { kind: 'degraded', summary: 'A job was queued but no worker is running to execute it; it waits until a worker runs.' },diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.tsindex e650f0cdcb..5e58913cb4 100644--- a/src/core/operation-manifest.generated.ts+++ b/src/core/operation-manifest.generated.ts@@ -6791,7 +6791,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["outputRedaction": {"exempt": "skill catalog files are installed instructions read verbatim; redaction would corrupt approved revisions"},- "description": "Run SkillOpt against a single skill. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.",+ "description": "Run SkillOpt against a single skill; its iterative loop (optimizer_mode \"reflect\") is deprecated and removed on or after 2026-12-03. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.","params": {"skill_name": {"type": "string",@@ -6844,7 +6844,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = ["one-shot-rewrite","reflect"],- "description": "Default one-shot-rewrite: one gated rewrite. reflect opts into the iterative edit loop, which has not yet beaten one-shot on gbrain benchmarks."+ "description": "Default one-shot-rewrite: one gated rewrite. reflect runs the iterative edit loop, which is deprecated (removed on or after 2026-12-03) and emits the skillopt_loop_deprecated notice."},"shared_skill": {"type": "boolean",diff --git a/src/core/ops/skillopt.ts b/src/core/ops/skillopt.tsindex 43afb4b2b8..bf72dc7fc0 100644--- a/src/core/ops/skillopt.ts+++ b/src/core/ops/skillopt.ts@@ -132,7 +132,7 @@ const run_skillopt: Operation = {name: 'run_skillopt',idempotent: true,outputRedaction: { exempt: 'skill catalog files are installed instructions read verbatim; redaction would corrupt approved revisions' },- description: 'Run SkillOpt against a single skill. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.',+ description: 'Run SkillOpt against a single skill; its iterative loop (optimizer_mode "reflect") is deprecated and removed on or after 2026-12-03. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.',params: {skill_name: { type: 'string', required: true, description: 'Kebab-case skill name (resolves to skills/<name>/SKILL.md)' },benchmark_path: { type: 'string', description: 'Absolute path to benchmark JSONL; defaults to skills/<name>/skillopt-benchmark.jsonl' },@@ -145,7 +145,7 @@ const run_skillopt: Operation = {allow_mutate_bundled: { type: 'boolean', description: 'Required to mutate bundled skills' },held_out_path: { type: 'string', description: 'Path to a held-out test set (JSONL). REQUIRED (>=5 rows) to mutate a bundled skill in place — otherwise the run hard-refuses. Remote callers: must resolve within the skills directory.' },dry_run: { type: 'boolean', description: 'Preview: models plan, strict verdict and cost estimate, no LLM calls' },- optimizer_mode: { type: 'string', enum: ['one-shot-rewrite', 'reflect'], description: 'Default one-shot-rewrite: one gated rewrite. reflect opts into the iterative edit loop, which has not yet beaten one-shot on gbrain benchmarks.' },+ optimizer_mode: { type: 'string', enum: ['one-shot-rewrite', 'reflect'], description: 'Default one-shot-rewrite: one gated rewrite. reflect runs the iterative edit loop, which is deprecated (removed on or after 2026-12-03) and emits the skillopt_loop_deprecated notice.' },shared_skill: { type: 'boolean', description: 'Optimize an exact shared catalog revision in a private proposal workspace and publish the accepted body through put_skill.' },source_id: { type: 'string', description: 'Required with shared_skill: canonical source.' },source_incarnation: { type: 'string', description: 'Required with shared_skill: exact catalog source incarnation.' },@@ -193,6 +193,7 @@ const run_skillopt: Operation = {if (optimizerMode !== 'one-shot-rewrite' && optimizerMode !== 'reflect') {throw invalidParam(ctx, 'run_skillopt', 'optimizer_mode', "run_skillopt: optimizer_mode must be 'one-shot-rewrite' or 'reflect'", { example: 'reflect' });}+ if (optimizerMode === 'reflect') ctx.emitNotice?.((await import('../skillopt/loop-deprecation.ts')).skillOptLoopDeprecatedNotice());const { clampRemoteReflectMaxTokens } = await import('../skillopt/output-cap.ts');let reflectMaxTokens: number | undefined;try {diff --git a/src/core/skillopt/help.ts b/src/core/skillopt/help.tsindex 37e44b2731..4fedbdfb4c 100644--- a/src/core/skillopt/help.ts+++ b/src/core/skillopt/help.ts@@ -9,8 +9,9 @@ of a frozen agent. Validation-gated, budget-capped, atomic-versioned.By default it runs ONE gated rewrite: a forward pass on one train batch, onewhole-body rewrite, then the selection gate. --loop runs the iterative edit-loop instead; on gbrain's benchmarks it has not yet beaten the one-shot rewrite-(same held-out score at ~1.8x the cost), so it is opt-in until it does.+loop instead. The loop is deprecated and will be removed on or after+2026-12-03: on gbrain's benchmarks it tied the one-shot rewrite (same held-out+score at ~1.8x the cost). Nothing replaces it; edit the skill directly.Based on SkillOpt (arXiv 2605.23904, MSR May 2026).@@ -56,6 +57,7 @@ Models:Modes:--loop Iterative reflect loop (edit ops, epochs).+ Deprecated: removed on or after 2026-12-03.Default is one gated one-shot rewrite.--dry-run Models plan, strict verdict + cost estimate,no LLM calls (exit 1 only on a strict failure)diff --git a/src/core/skillopt/job.ts b/src/core/skillopt/job.tsindex 0cd3aa14bb..fadc1f1f2d 100644--- a/src/core/skillopt/job.ts+++ b/src/core/skillopt/job.ts@@ -22,6 +22,7 @@ import {} from './models-plan.ts';import { runSkillOpt } from './orchestrator.ts';import { clampRemoteReflectMaxTokens } from './output-cap.ts';+import { noteSkillOptLoopDeprecated } from './loop-deprecation.ts';import type { SkillOptOpts } from './types.ts';export type SkillOptJobInput = Pick<SkillOptOpts,@@ -99,6 +100,9 @@ export async function runSkillOptJob(engine: BrainEngine, rawData: unknown): Prothrow new Error(`skillopt handler: missing required job.data fields (skills_dir, skill_name, benchmark_path)`);}const models = await resolveJobModels(engine, data);+ // A job queued before one-shot became the default carries no mode: it was queued for the loop.+ const optimizerMode = data.optimizer_mode === 'one-shot-rewrite' ? 'one-shot-rewrite' : 'reflect';+ noteSkillOptLoopDeprecated(optimizerMode);const result = await runSkillOpt({engine,skillName,@@ -113,8 +117,7 @@ export async function runSkillOptJob(engine: BrainEngine, rawData: unknown): PromodelsStrict: data.models_strict === true,reflectMaxTokens: clampRemoteReflectMaxTokens(data.reflect_max_tokens),mode: (data.mode as 'patch' | 'rewrite') ?? 'patch',- // A job queued before one-shot became the default carries no mode: it was queued for the loop.- optimizerMode: data.optimizer_mode === 'one-shot-rewrite' ? 'one-shot-rewrite' : 'reflect',+ optimizerMode,dryRun: Boolean(data.dry_run),noMutate: Boolean(data.no_mutate),allowMutateBundled: Boolean(data.allow_mutate_bundled),diff --git a/src/core/skillopt/loop-deprecation.ts b/src/core/skillopt/loop-deprecation.tsnew file mode 100644index 0000000000..92fd1dbfa6--- /dev/null+++ b/src/core/skillopt/loop-deprecation.ts@@ -0,0 +1,24 @@+/**+ * GST-1251: SkillOpt's iterative reflect loop is deprecated and is removed on or after SKILLOPT_LOOP_REMOVAL_DATE.+ * Each entry point that runs it (the CLI's `--loop` or a resumed loop checkpoint, `run_skillopt` with+ * `optimizer_mode: "reflect"`, a `skillopt` job in reflect mode) emits the `skillopt_loop_deprecated` coaching+ * notice once per use; the run itself is unchanged.+ */+import type { Notice } from '../agent-output.ts';+import type { OptimizerMode } from './types.ts';++export const SKILLOPT_LOOP_REMOVAL_DATE = '2026-12-03';++export const SKILLOPT_LOOP_DEPRECATED = `SkillOpt's iterative loop (--loop, optimizer_mode "reflect") is deprecated and will be removed on or after ${SKILLOPT_LOOP_REMOVAL_DATE}; this run continues unchanged. `+ + 'Nothing replaces it: edit the skill directly, or run the default one-shot rewrite (gbrain skillopt <skill> without --loop), '+ + "which matched the loop's held-out score on gbrain-evals' benchmarks at about half the cost.";++export function skillOptLoopDeprecatedNotice(): Notice {+ return { code: 'skillopt_loop_deprecated', kind: 'coaching', why: SKILLOPT_LOOP_DEPRECATED };+}++/** Prints the notice on stderr when `mode` runs the loop (the CLI command and the job handler call it once per run). */+export function noteSkillOptLoopDeprecated(mode: OptimizerMode): void {+ if (mode !== 'reflect') return;+ process.stderr.write(`[gbrain notice skillopt_loop_deprecated] ${SKILLOPT_LOOP_DEPRECATED}\n`);+}diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.jsonindex a6bd83ffc0..b309b57906 100644--- a/test/fixtures/goldens/cli/tools-json.json+++ b/test/fixtures/goldens/cli/tools-json.json@@ -2,8 +2,8 @@"golden": {"exitCode": 0,"stderr": "",- "stdoutBytes": 268798,- "stdoutSha256": "7e8ad692baa54268f6f79bf3109bfb03bf6c29119f65624e8847aff30963f591",+ "stdoutBytes": 268935,+ "stdoutSha256": "c93966124678ecbf3623a199aeebea8b5eac5e8d990bd4c9622531affc20a7bc","toolNames": ["remember","entity",@@ -7879,7 +7879,7 @@"scope": "admin"},{- "description": "Run SkillOpt against a single skill. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.",+ "description": "Run SkillOpt against a single skill; its iterative loop (optimizer_mode \"reflect\") is deprecated and removed on or after 2026-12-03. Admin scope and remote skill allowlist required. shared_skill stages an exact catalog revision privately and requires explicit skill_editor and put_skill grants; only accepted body changes publish through the original revision CAS. Rate-limited per-skill via DB lock.","idempotent": true,"local_only": false,"mutating": true,@@ -7948,7 +7948,7 @@"type": "boolean"},"optimizer_mode": {- "description": "Default one-shot-rewrite: one gated rewrite. reflect opts into the iterative edit loop, which has not yet beaten one-shot on gbrain benchmarks.",+ "description": "Default one-shot-rewrite: one gated rewrite. reflect runs the iterative edit loop, which is deprecated (removed on or after 2026-12-03) and emits the skillopt_loop_deprecated notice.","enum": ["one-shot-rewrite","reflect"diff --git a/test/skillopt/loop-deprecation.serial.test.ts b/test/skillopt/loop-deprecation.serial.test.tsnew file mode 100644index 0000000000..1d4e2fb391--- /dev/null+++ b/test/skillopt/loop-deprecation.serial.test.ts@@ -0,0 +1,189 @@+/**+ * GST-1251: SkillOpt's iterative loop is deprecated (removal on or after 2026-12-03). Each entry point that runs the+ * loop emits the `skillopt_loop_deprecated` coaching notice exactly once per use, and an entry point that runs the+ * default one-shot rewrite emits none: the CLI (`--loop`, and a `--resume` of a checkpoint the loop wrote), the+ * run_skillopt op (`optimizer_mode: "reflect"`, rendered by MCP dispatch and the CLI op channel), and the background+ * job handler (a reflect job, and a job queued before one-shot became the default, which carries no mode). The cycle+ * phase only runs the one-shot rewrite. The run itself is unchanged: the loop still reaches runSkillOpt as 'reflect'.+ *+ * Serial lane (isolation rule R2): runSkillOpt and repo-root are mocked with mock.module and every path is loaded+ * after the mocks, so no path launches a real run.+ */+import { describe, test, expect, beforeAll, afterAll, beforeEach, afterEach, mock } from 'bun:test';+import * as fs from 'node:fs';+import * as os from 'node:os';+import * as path from 'node:path';++const skillsDir = fs.mkdtempSync(path.join(os.tmpdir(), 'skillopt-loop-deprecation-'));+const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'skillopt-loop-deprecation-home-'));+const SKILL = 'loop-skill';+fs.mkdirSync(path.join(skillsDir, SKILL), { recursive: true });+fs.writeFileSync(path.join(skillsDir, SKILL, 'skillopt-benchmark.jsonl'), '{}\n');++let captured: Array<Record<string, unknown>> = [];+mock.module('../../src/core/skillopt/orchestrator.ts', () => ({+ runSkillOpt: async (opts: Record<string, unknown>) => {+ captured.push(opts);+ return {+ outcome: 'no_improvement',+ receipt: { run_id: 'r', skill: SKILL, final_cost_usd: 0, best_sel_score: 0, models_plan: [], models_strict: { enabled: false, ok: true, violations: [] } },+ finalText: '',+ mutatedSkillFile: false,+ };+ },+ parseSplit: (s: string) => s.split(':').map(Number),+}));+mock.module('../../src/core/repo-root.ts', () => ({+ autoDetectSkillsDirReadOnly: () => ({ dir: skillsDir }),+}));++import { PGLiteEngine } from '../../src/core/pglite-engine.ts';+import { resetPgliteState } from '../helpers/reset-pglite.ts';+import { withEnv } from '../helpers/with-env.ts';+import { runSkillOptCommand } from '../../src/commands/skillopt.ts';+import { operations, type OperationContext } from '../../src/core/operations.ts';+import { runPhaseSkillopt } from '../../src/core/skillopt/cycle-phase.ts';+import { buildSkillOptJobData, runSkillOptJob } from '../../src/core/skillopt/job.ts';+import { resolveSkillOptModels } from '../../src/core/skillopt/models-plan.ts';+import { checkpointPath } from '../../src/core/skillopt/checkpoint.ts';+import { NOTICE_CODES } from '../../src/core/error-registry.ts';+import type { Notice } from '../../src/core/agent-output.ts';+import { SKILLOPT_LOOP_DEPRECATED, SKILLOPT_LOOP_REMOVAL_DATE } from '../../src/core/skillopt/loop-deprecation.ts';++const NOTICE_LINE = /\[gbrain notice skillopt_loop_deprecated\]/g;+const ENV = { GBRAIN_HOME: tmpHome, ANTHROPIC_API_KEY: 'sk-ant-test', OPENAI_API_KEY: undefined, GBRAIN_MODEL: undefined, GBRAIN_MODEL_DISCOVERY: 'off' };++let engine: PGLiteEngine;+const origWrite = { out: process.stdout.write.bind(process.stdout), err: process.stderr.write.bind(process.stderr) };+const origExit = process.exit;+let stderr = '';+class ExitSignal extends Error {}++async function viaCli(args: string[]): Promise<void> {+ try {+ await runSkillOptCommand(engine, [SKILL, '--skills-dir', skillsDir, '--json', ...args]);+ } catch (err) {+ if (!(err instanceof ExitSignal)) throw err;+ }+}++async function viaOp(params: Record<string, unknown>): Promise<Notice[]> {+ const notices: Notice[] = [];+ const op = operations.find((o) => o.name === 'run_skillopt')!;+ await op.handler({ engine, config: {}, logger: console, dryRun: false, remote: false, emitNotice: (n: Notice) => { notices.push(n); } } as unknown as OperationContext,+ { skill_name: SKILL, ...params });+ return notices;+}++async function viaJob(optimizerMode: 'reflect' | 'one-shot-rewrite' | null): Promise<void> {+ const data = buildSkillOptJobData({+ skillsDir, skillName: SKILL, benchmarkPath: path.join(skillsDir, SKILL, 'skillopt-benchmark.jsonl'),+ epochs: 1, batchSize: 2, lr: 4, lrSchedule: 'constant', split: [4, 1, 5], mode: 'patch', optimizerMode: optimizerMode ?? 'reflect', dryRun: false,+ noMutate: false, allowMutateBundled: false, bootstrapReviewed: false, maxCostUsd: 5, maxRuntimeMin: 30, force: false,+ models: await resolveSkillOptModels(engine, {}), modelFlags: {}, modelsStrict: false,+ }) as Record<string, unknown>;+ if (optimizerMode === null) delete data.optimizer_mode;+ await runSkillOptJob(engine, JSON.parse(JSON.stringify(data)));+}++beforeAll(async () => {+ engine = new PGLiteEngine();+ await engine.connect({});+ await engine.initSchema();+}, 60_000);++afterAll(async () => {+ await engine.disconnect();+ fs.rmSync(skillsDir, { recursive: true, force: true });+ fs.rmSync(tmpHome, { recursive: true, force: true });+});++beforeEach(async () => {+ await resetPgliteState(engine);+ captured = [];+ stderr = '';+ process.stdout.write = (() => true) as typeof process.stdout.write;+ process.stderr.write = ((c: string | Uint8Array) => { stderr += String(c); return true; }) as typeof process.stderr.write;+ process.exit = (() => { throw new ExitSignal(); }) as typeof process.exit;+});++afterEach(() => {+ process.stdout.write = origWrite.out;+ process.stderr.write = origWrite.err;+ process.exit = origExit;+});++test('the notice is a registered coaching code that names the removal date and the replacement', () => {+ expect(NOTICE_CODES.skillopt_loop_deprecated).toMatchObject({ kind: 'coaching' });+ expect(SKILLOPT_LOOP_REMOVAL_DATE).toBe('2026-12-03');+ expect(SKILLOPT_LOOP_DEPRECATED).toContain('on or after 2026-12-03');+ expect(SKILLOPT_LOOP_DEPRECATED).toContain('Nothing replaces it');+ expect(SKILLOPT_LOOP_DEPRECATED).toContain('edit the skill directly');+});++describe('CLI', () => {+ test('--loop prints the notice once and still runs the loop', async () => {+ await withEnv(ENV, () => viaCli(['--loop']));+ expect(stderr.match(NOTICE_LINE)).toHaveLength(1);+ expect(stderr).toContain(SKILLOPT_LOOP_DEPRECATED);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['reflect']);+ });++ test('--resume of a checkpoint the loop wrote prints the notice once', async () => {+ const file = checkpointPath(skillsDir, SKILL, 'run-loop');+ fs.mkdirSync(path.dirname(file), { recursive: true });+ fs.writeFileSync(file, JSON.stringify({ schema: 1, run_id: 'run-loop', run_spec: { optimizer_mode: 'reflect' } }));+ try {+ await withEnv(ENV, () => viaCli(['--resume', 'run-loop']));+ } finally {+ fs.rmSync(file, { force: true });+ }+ expect(stderr.match(NOTICE_LINE)).toHaveLength(1);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['reflect']);+ });++ test('the default one-shot rewrite prints no notice', async () => {+ await withEnv(ENV, () => viaCli([]));+ expect(stderr).not.toContain('skillopt_loop_deprecated');+ expect(captured.map((c) => c.optimizerMode)).toEqual(['one-shot-rewrite']);+ });+});++describe('run_skillopt op (MCP and the CLI op channel)', () => {+ test('optimizer_mode "reflect" emits the notice once and still runs the loop', async () => {+ const notices = await withEnv(ENV, () => viaOp({ optimizer_mode: 'reflect' }));+ expect(notices.filter((n) => n.code === 'skillopt_loop_deprecated')).toEqual([{ code: 'skillopt_loop_deprecated', kind: 'coaching', why: SKILLOPT_LOOP_DEPRECATED }]);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['reflect']);+ });++ test('the default mode emits no notice', async () => {+ const notices = await withEnv(ENV, () => viaOp({}));+ expect(notices.filter((n) => n.code === 'skillopt_loop_deprecated')).toEqual([]);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['one-shot-rewrite']);+ });+});++describe('background job handler', () => {+ test('a reflect job prints the notice once', async () => {+ await withEnv(ENV, () => viaJob('reflect'));+ expect(stderr.match(NOTICE_LINE)).toHaveLength(1);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['reflect']);+ });++ test('a job queued before one-shot became the default (no mode) runs the loop and prints the notice once', async () => {+ await withEnv(ENV, () => viaJob(null));+ expect(stderr.match(NOTICE_LINE)).toHaveLength(1);+ expect(captured.map((c) => c.optimizerMode)).toEqual(['reflect']);+ });++ test('a one-shot job prints no notice', async () => {+ await withEnv(ENV, () => viaJob('one-shot-rewrite'));+ expect(stderr).not.toContain('skillopt_loop_deprecated');+ });+});++test('the cycle phase runs the one-shot rewrite and prints no notice', async () => {+ await withEnv(ENV, () => runPhaseSkillopt({ engine, once: true }));+ expect(stderr).not.toContain('skillopt_loop_deprecated');+ expect(captured.every((c) => c.optimizerMode === 'one-shot-rewrite')).toBe(true);+});