Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs: one-shot default in the skillopt guide, tutorial and key-files (Step 14.5 audit)

garrytanc487837c52df
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index 7d41635e5c..a7f26103d4 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -23,9 +23,9 @@ 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`. 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); 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). Three eval-internal ablation opts on `SkillOptOpts` (NOT on CLI): `reflectMode` (`'both'`/`'failure-only'`), `disableValidationGate` (greedy-accept), `optimizerMode` (`'reflect'`/`'one-shot-rewrite'`), recorded in `RunReceipt` + audit `run_start` for replayability; `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; 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); 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 eval-internal one-shot ablation, 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`.
+- `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`.
- `src/core/skillpack/{init-brain-pack,brain-pack-advisory,brain-resident-locate,nag-state}.ts` — brain-resident skillpacks. `manifest-v1.ts` gains optional `brain_resident` + `schema_pack` (additive). `runInitBrainPack` scaffolds a pack beside brain content (`brain_resident:true`, exact `gbrain_min_version`, 5-section machine-parseable README); `applyWritePlan` is factored out of `init-scaffold.ts` for the shared refuse-overwrite loop. Topology A: `src/commands/sources.ts` `runAdd` prints `brain-pack-advisory` to stderr after `opsAddSource`, fail-open; `nag-state.ts` (`~/.gbrain/skillpack-nag-state.json`) keys declines by `(source-repo brain_id, source_id, pack_name)` with pure `decideNagAction` (first/reminder/version-bump/ceiling) — declines count ONLY on CLI-interactive displays. Topology B: `brain-resident-locate.loadResidentPacksForServer` (source-scoped via `sourceScopeOpts`) backs the `list_brain_skillpack` op; `getResidentSkillDetail` backs `get_skill` `source_id`; `scaffold_spec` is the git source, never a server FS path. Tests: `test/skillpack-{init-brain-pack,nag-state,brain-resident-locate}.test.ts` + the brain-resident cases in `test/skillpack-manifest-v1.test.ts`.
diff --git a/docs/guides/skillopt.md b/docs/guides/skillopt.md
index 80635db39e..576449d248 100644
--- a/docs/guides/skillopt.md
+++ b/docs/guides/skillopt.md
@@ -98,10 +98,10 @@ the audit event only; the full meta-edit proposal is a tracked follow-up.
| `--bootstrap-tasks N` | 15 | How many starter tasks `--bootstrap-from-skill` generates (max 50) |
| `--bootstrap-from-routing` | off | Auto-build benchmark from routing-eval.jsonl |
| `--bootstrap-reviewed` | off | Required after human-reviewing bootstrap output |
-| `--epochs N` | 4 | Outer-loop iterations |
-| `--batch-size N` | 8 | Tasks per inner step |
-| `--lr N` | 4 | Max edits per step |
-| `--lr-schedule cosine\|linear\|constant` | cosine | Edit-budget decay |
+| `--epochs N` | 4 | Outer-loop iterations (`--loop` only) |
+| `--batch-size N` | 8 | Tasks per inner step (the one-shot forward-pass size) |
+| `--lr N` | 4 | Max edits per step (`--loop` only) |
+| `--lr-schedule cosine\|linear\|constant` | cosine | Edit-budget decay (`--loop` only) |
| `--split TRAIN:SEL:TEST` | 4:1:5 | Ratio; refuses if D_sel < 5 |
| `--optimizer-model MODEL` | tier.deep | Reflects + proposes |
| `--target-model MODEL` | tier.subagent | Executes the skill |
@@ -241,8 +241,8 @@ The reflect codes are emitted with a mode, as `reflect_failure_<class>` or
| <a id="reflect_context_overflow"></a>`reflect_context_overflow` | Provider rejected the prompt as too long | Same as above, detected by the provider | Lower the cap, or use a larger-window `--optimizer-model` |
| <a id="reflect_failed"></a>`reflect_failed` | Reflect provider call failed | Provider/network/auth error | Check `gbrain models doctor`, then resume |
| <a id="one_shot_rewrite_truncated"></a>`one_shot_rewrite_truncated` | One-shot rewrite hit the output cap; nothing promoted | Cap too small for a full rewrite | Raise `--reflect-max-tokens` / `skillopt.reflect_max_tokens` |
-| <a id="one_shot_rewrite_output_cap_too_small"></a>`one_shot_rewrite_output_cap_too_small` | One-shot refused before calling: the body cannot fit the cap | `ceil(body chars / 3) + 1024` exceeds the cap | Raise the cap, or use the default reflect mode |
-| <a id="one_shot_rewrite_body_truncated"></a>`one_shot_rewrite_body_truncated` | One-shot refused: the body had to be truncated | Skill body larger than the optimizer's context | Lower the reflect cap (it shares the window), use a larger-window `--optimizer-model`, or use reflect mode |
+| <a id="one_shot_rewrite_output_cap_too_small"></a>`one_shot_rewrite_output_cap_too_small` | One-shot refused before calling: the body cannot fit the cap | `ceil(body chars / 3) + 1024` exceeds the cap | Raise the cap, or use `--loop` |
+| <a id="one_shot_rewrite_body_truncated"></a>`one_shot_rewrite_body_truncated` | One-shot refused: the body had to be truncated | Skill body larger than the optimizer's context | Lower the reflect cap (it shares the window), use a larger-window `--optimizer-model`, or use `--loop` |
| <a id="one_shot_rewrite_empty_reply"></a>`one_shot_rewrite_empty_reply` | One-shot reply was empty | Optimizer is not following the rewrite contract | Try a different `--optimizer-model` |
| <a id="one_shot_rewrite_failed"></a>`one_shot_rewrite_failed` | One-shot provider call failed | Provider/network/auth error | Check `gbrain models doctor`, then resume |
| <a id="budget_exhausted"></a>`budget_exhausted` | Run aborted at the cost cap | Spend (including each call's full-cap reservation) reached `--max-cost-usd`; or, when the detail says `no_pricing`, gbrain has no price for a model, so the cap cannot be enforced | Raise `--max-cost-usd` (cycle: `cycle.skillopt.per_skill_cap_usd`), or lower the reflect cap. For `no_pricing`: look up the model's price and run the `gbrain pricing set` command the receipt's `no_pricing.register_command` names, then resume ([registering a model price](../operations/spend-controls.md#registering-a-model-price)) |
@@ -269,7 +269,7 @@ Example `errored` summary (stderr):
[skillopt] Fix (reflect_truncated): The optimizer ran out of output tokens. Raise the cap: --reflect-max-tokens <n> or gbrain config set skillopt.reflect_max_tokens <n>. See docs/guides/skillopt.md#reflect_truncated
[skillopt] Run id: so-20260928-1a2b3c
[skillopt] Checkpoint: skills/meeting-prep/skillopt/checkpoint-so-20260928-1a2b3c.json
-[skillopt] Resume: gbrain skillopt meeting-prep --resume so-20260928-1a2b3c --skills-dir skills --benchmark skills/meeting-prep/skillopt-benchmark.jsonl --split 4:1:5 --epochs 4 --batch-size 8 --lr 4 --lr-schedule cosine --optimizer-model openai:gpt-5.2 --target-model anthropic:claude-sonnet-5 --judge-model anthropic:claude-sonnet-5 --reflect-max-tokens 8192 --max-cost-usd 5 --max-runtime-min 30
+[skillopt] Resume: gbrain skillopt meeting-prep --resume so-20260928-1a2b3c --skills-dir skills --benchmark skills/meeting-prep/skillopt-benchmark.jsonl --split 4:1:5 --epochs 4 --batch-size 8 --lr 4 --lr-schedule cosine --optimizer-model openai:gpt-5.2 --target-model anthropic:claude-sonnet-5 --judge-model anthropic:claude-sonnet-5 --reflect-max-tokens 8192 --loop --max-cost-usd 5 --max-runtime-min 30
```
## Model provenance
@@ -492,7 +492,9 @@ around it; fix the code and re-benchmark instead.
### Sizing `--max-cost-usd`
The preflight estimate is a floor, not a ceiling — reflect retries, judge
-re-runs, and the held-out gate add real spend. Rough per-run scaling:
+re-runs, and the held-out gate add real spend. Rough per-run scaling for
+`--loop` (the default one-shot rewrite makes one forward pass of `--batch-size`
+tasks, one gated rewrite and one gate pass):
rollouts ≈ (epochs × steps_per_epoch × batch_size × 1) # forward passes
+ (accept-gate candidates × |D_sel| × 3) # median-of-3
diff --git a/docs/tutorials/improving-skills-with-skillopt.md b/docs/tutorials/improving-skills-with-skillopt.md
index 1161fb7d75..e62933ad20 100644
--- a/docs/tutorials/improving-skills-with-skillopt.md
+++ b/docs/tutorials/improving-skills-with-skillopt.md
@@ -179,10 +179,12 @@ $0.70–$1.00. The preflight refuses to start a real run whose estimate exceeds
gbrain skillopt meeting-prep --split 1:1:1
```
-You'll watch it work: a baseline eval to set the bar, then per-step forward passes
-(run the skill), backward passes (propose edits), and a validation gate that
-runs each sel task's judge 3 times and takes the median — accepting only if the
-median beats the current best by more than 0.05.
+You'll watch it work: a baseline eval to set the bar, one forward pass over a
+batch of train tasks (run the skill), one rewrite of the skill body from those
+rollouts, and a validation gate that runs each sel task's judge 3 times and
+takes 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
+[reference guide](../guides/skillopt.md#one-shot-rewrite-the-default).)
When it finishes, the last lines tell you everything: