Skip to content

Commit faf4700

Browse files
feat(sleep): adopt reviewed skill subsets safely (#212)
* feat(sleep): adopt reviewed skill subsets safely * fix(sleep): wire cycle staging and adopt-time review checks Address PR 212 review: run_sleep_cycle stages resolved SkillProposals, status/adopt list and select a subset, uniqueness is rechecked at adopt, and a failed adopted_skills.json write rolls live files back. Refs #212 * test(sleep): mega-cover PR 212 review paths Adversarial CLI, adopt-time, cycle-staging, and auto-adopt cases for Yifan's five review items. Also tidy isort on the files this slice touches. Refs #120 * fix(sleep): pin staged skill hashes and confine adopt targets Harden PR 212 adopt: sha256 pin each staged skill, revalidate the whole manifest before any live write, refuse symlink/missing-parent targets, skip notes on the cycle report, and reject empty --skill. Refs #212 * fix(sleep): harden multi-skill fan-out adoption end to end --------- Co-authored-by: Yif-Yang <[email protected]>
1 parent fb1c305 commit faf4700

40 files changed

Lines changed: 8327 additions & 332 deletions

‎CHANGELOG.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,17 @@ All notable changes to SkillOpt are documented here. This project adheres to
77
## [Unreleased]
88

99
### Added
10+
- **SkillOpt-Sleep multi-skill fan-out and reviewed subset adoption**: each
11+
hinted skill is consolidated from its own pinned live baseline, staged as an
12+
independent proposal with per-skill gate evidence, and promoted only through
13+
an explicit `--skill`, `--all-skills`, or managed `--legacy` choice. Adoption
14+
uses a versioned fail-closed manifest, provenance hashes, canonical target
15+
pins, immutable backups/receipts, cross-night locking, durable publication,
16+
and restart-recoverable transactions. Fan-out discovers native project skill
17+
roots, supports repeatable `--skill-root` overrides, and is enabled by
18+
`multi_skill_fanout` (`multi_skill_report` remains an alias). MCP adapters
19+
enforce typed arguments and preserve engine failures without copying outside
20+
the transaction (thanks @bogdanbaciu21, #212).
1021
- Additive `section_contains` rule-judge operator for literal,
1122
case-insensitive matching within numbered, bilingual, or annotated ATX
1223
Markdown headings. The legacy `section_present` behavior is unchanged.
@@ -120,8 +131,8 @@ All notable changes to SkillOpt are documented here. This project adheres to
120131
Thank you to the contributors behind this unreleased work:
121132
@AKhozya, @Alphaxalchemy, @Phoenix0531-sudo, @SparshGarg999,
122133
@Tanmay9223, @chirag127, @codeL1985, @dimitarvdenev,
123-
@ichoosetoaccept, @jcforever1, @nankingjing, @wilyan09007, @xs229, and
124-
@zixuanguo786-ctrl.
134+
@bogdanbaciu21, @ichoosetoaccept, @jcforever1, @nankingjing, @wilyan09007,
135+
@xs229, and @zixuanguo786-ctrl.
125136

126137
## [0.2.0] — 2026-07-02
127138

‎docs/guide/installation.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,9 @@ checkout for those files.
2828
The generic research `openai_compatible` backend, SkillOpt-Sleep handoff,
2929
Sleep support for non-Azure OpenAI-compatible endpoints, the Sleep
3030
`--preferences` flag, Cursor source/backend/plugin support, and Pi
31-
source/backend support landed after that release and require a source
32-
install from `main` until the next release.
31+
source/backend support, multi-skill fan-out, and reviewed subset adoption
32+
landed after that release and require a source install from `main` until
33+
the next release.
3334

3435
### Source checkout
3536

‎docs/reference/cli.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,9 @@
55
> Sleep support for non-Azure OpenAI-compatible endpoints, the Sleep
66
> `--preferences` flag, the research `cursor_exec` target harness, or Cursor
77
> source/backend/plugin support, Pi source/backend support, OpenCode Sleep
8-
> source/backend support, or VS Code Copilot transcript harvesting; use a source
9-
> install from `main` for those features until the next release.
8+
> source/backend support, VS Code Copilot transcript harvesting, or multi-skill
9+
> fan-out and subset adoption; use a source install from `main` for those
10+
> features until the next release.
1011
1112
## Training
1213

@@ -144,11 +145,25 @@ Actions are `run`, `dry-run`, `status`, `adopt`, `harvest`, `schedule`, and
144145
| `--lookback-hours N` | Initial transcript lookback; `0` scans all history |
145146
| `--max-sessions N` / `--max-tasks N` | Bound the harvested workload |
146147
| `--target-skill-path PATH` | Explicit skill document to stage/adopt |
148+
| `--skill-root PATH` | Add a skill-resolution root; repeatable, with relative paths resolved below `--project` |
147149
| `--tasks-file PATH` | Replay a reviewed task JSON file instead of harvesting |
148150
| `--edit-budget N` | Maximum bounded edits for the night |
149151
| `--progress` / `--json` | Progress or machine-readable output |
150152
| `--auto-adopt` | Apply an accepted staged proposal automatically |
151153

154+
`adopt` also accepts `--skill NAME` (repeatable) and `--all-skills` for a night
155+
that staged per-skill proposals. Use `--legacy` to adopt only a co-staged
156+
managed `SKILL.md` / `CLAUDE.md` proposal. Bare `adopt` on a fan-out night lists
157+
the names and exits instead of promoting anything. A leading-dash name must use
158+
the unambiguous `--skill=--name` form. See
159+
[multi-skill staging](../sleep/multi-skill-staging.md).
160+
161+
Fan-out resolves existing project-native `.agents/skills`, `.claude/skills`,
162+
`.cursor/skills`, and `.devin/skills` directories plus the established Claude
163+
roots. Use `--skill-root` for another integration-specific location. Configure
164+
the canonical `multi_skill_fanout` key to enable proposal fan-out;
165+
`multi_skill_report` remains a compatibility alias.
166+
152167
The `mock` and `handoff` backends make no network calls. A real backend sends
153168
mining, replay, judging, and reflection prompts derived from harvested
154169
transcripts and tasks to its selected provider. Review that provider's

‎docs/sleep/README.md‎

Lines changed: 38 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -100,16 +100,18 @@ pip install skillopt # installs the engine + the `skillopt-sleep` command
100100
skillopt-sleep dry-run # harvest + mine + replay, report only; stages nothing
101101
skillopt-sleep run # a full nightly cycle; the proposal is staged for review
102102
skillopt-sleep status # show state + the latest staged proposal
103-
skillopt-sleep adopt # apply the latest staged proposal
103+
skillopt-sleep adopt --legacy # apply a reviewed managed proposal
104+
skillopt-sleep adopt --skill NAME # adopt one staged skill (repeatable)
105+
skillopt-sleep adopt --all-skills # adopt every still-pending fan-out skill
104106
skillopt-sleep schedule # install a nightly cron entry for this project
105107
```
106108

107109
> **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base
108110
> commands above. Cursor source/backend/plugin support, VS Code Copilot
109111
> transcript harvesting, Pi source/backend support, Sleep handoff, non-Azure
110112
> OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and
111-
> `--preferences` landed later and require a source install from `main` until
112-
> the next release.
113+
> `--preferences`, multi-skill fan-out, and reviewed subset adoption landed
114+
> later and require a source install from `main` until the next release.
113115
114116
The per-agent integrations below still come from the repo; the CLI above is the
115117
standalone, pip-only way to run a cycle. Claude Code, Codex, Cursor, Copilot, and
@@ -292,22 +294,38 @@ documents the separate HTTPS-only boundary for Azure managed-identity credential
292294
Deterministic proof (no API key):
293295
`python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves`.
294296

295-
### Opt-in: per-skill group reporting
297+
### Opt-in: per-skill fan-out
296298

297-
Set `"multi_skill_report": true` in `~/.skillopt-sleep/config.json` to add an
298-
independent gate result and report row for every explicit skill hint mined that
299-
night:
299+
Set `"multi_skill_fanout": true` in `~/.skillopt-sleep/config.json` to add an
300+
independent gate result and reviewable proposal for every explicit skill hint
301+
mined that night. `multi_skill_report` remains a compatibility alias:
300302

301303
```json
302-
{"multi_skill_report": true}
304+
{"multi_skill_fanout": true}
303305
```
304306

305307
This runs one additional consolidation per group (including a catch-all group when
306-
hinted and unhinted evidence are mixed), so it increases backend calls and token use.
307-
It is reporting-only for now: every group starts from the same managed skill
308-
document, and Sleep does not yet resolve and update several live `SKILL.md` files
309-
automatically. Nights containing only the managed catch-all group keep the existing
310-
single-consolidation behavior.
308+
hinted and unhinted evidence are mixed), so it multiplies backend calls and token
309+
use; configured dream rollouts and synthetic variants multiply the per-group work
310+
too. Each group inherits the configured edit budget, gate mode/metric,
311+
`gate_no_regression`, `dream_rollouts`, `dream_factor`, `recall_k`, and
312+
`evolve_skill`. Recalled archive tasks are restricted to that same skill hint;
313+
shared memory is read-only in fan-out runs. Setting `evolve_skill` to `false`
314+
therefore disables per-skill proposals as well as the managed skill proposal.
315+
316+
Each explicitly hinted group resolves and reads its own live `SKILL.md` before
317+
consolidation, so its staged proposal preserves that skill's baseline. Missing,
318+
ambiguous, unreadable, aliased, or colliding skills are skipped and reported
319+
instead of falling back to the managed document. Adoption remains review-driven:
320+
choose fan-out proposals with `adopt --skill NAME` or `--all-skills`, and use
321+
`adopt --legacy` for a co-staged managed skill/memory pair. `auto_adopt` never
322+
promotes the per-skill fan-out. Nights containing only the managed catch-all group
323+
keep the existing single-consolidation behavior.
324+
325+
Resolution searches existing project-native `.agents/skills`, `.claude/skills`,
326+
`.cursor/skills`, and `.devin/skills` directories, then the established Claude
327+
home and plugin-cache roots. Add repeatable `--skill-root PATH` values when an
328+
integration stores skills elsewhere. Relative roots resolve below `--project`.
311329

312330
### Opt-in: experience replay & dream rollouts
313331

@@ -363,6 +381,13 @@ gate keeps the worst case bounded; keep it **on** by default.
363381

364382
## Learn more
365383

384+
The **low-level** API for staging one proposal per skill and adopting a reviewed
385+
subset (`staged_skills` / `adopt_skills`, plus `status` and `adopt --skill`) is
386+
documented in [`docs/sleep/multi-skill-staging.md`](multi-skill-staging.md).
387+
That page also documents the opt-in nightly fan-out, where every hinted group
388+
derives its proposal from its own resolved live `SKILL.md` while adoption remains
389+
an explicit human decision.
390+
366391
See the [SkillOpt documentation index](../index.md), the
367392
[CLI reference](../reference/cli.md), and the integration-specific READMEs under
368393
[`plugins/`](https://github.com/microsoft/SkillOpt/tree/main/plugins).

0 commit comments

Comments
 (0)