feat(sleep): adopt reviewed skill subsets safely

CHANGELOG.md

@@ -7,6 +7,17 @@ All notable changes to SkillOpt are documented here. This project adheres to
 ## [Unreleased]
 
 ### Added
+- **SkillOpt-Sleep multi-skill fan-out and reviewed subset adoption**: each
+  hinted skill is consolidated from its own pinned live baseline, staged as an
+  independent proposal with per-skill gate evidence, and promoted only through
+  an explicit `--skill`, `--all-skills`, or managed `--legacy` choice. Adoption
+  uses a versioned fail-closed manifest, provenance hashes, canonical target
+  pins, immutable backups/receipts, cross-night locking, durable publication,
+  and restart-recoverable transactions. Fan-out discovers native project skill
+  roots, supports repeatable `--skill-root` overrides, and is enabled by
+  `multi_skill_fanout` (`multi_skill_report` remains an alias). MCP adapters
+  enforce typed arguments and preserve engine failures without copying outside
+  the transaction (thanks @bogdanbaciu21, #212).
 - Additive `section_contains` rule-judge operator for literal,
   case-insensitive matching within numbered, bilingual, or annotated ATX
   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
 Thank you to the contributors behind this unreleased work:
 @AKhozya, @Alphaxalchemy, @Phoenix0531-sudo, @SparshGarg999,
 @Tanmay9223, @chirag127, @codeL1985, @dimitarvdenev,
-@ichoosetoaccept, @jcforever1, @nankingjing, @wilyan09007, @xs229, and
-@zixuanguo786-ctrl.
+@bogdanbaciu21, @ichoosetoaccept, @jcforever1, @nankingjing, @wilyan09007,
+@xs229, and @zixuanguo786-ctrl.
 
 ## [0.2.0] — 2026-07-02
 

docs/guide/installation.md

@@ -28,8 +28,9 @@ checkout for those files.
     The generic research `openai_compatible` backend, SkillOpt-Sleep handoff,
     Sleep support for non-Azure OpenAI-compatible endpoints, the Sleep
     `--preferences` flag, Cursor source/backend/plugin support, and Pi
-    source/backend support landed after that release and require a source
-    install from `main` until the next release.
+    source/backend support, multi-skill fan-out, and reviewed subset adoption
+    landed after that release and require a source install from `main` until
+    the next release.
 
 ### Source checkout
 

docs/reference/cli.md

@@ -5,8 +5,9 @@
 > Sleep support for non-Azure OpenAI-compatible endpoints, the Sleep
 > `--preferences` flag, the research `cursor_exec` target harness, or Cursor
 > source/backend/plugin support, Pi source/backend support, OpenCode Sleep
-> source/backend support, or VS Code Copilot transcript harvesting; use a source
-> install from `main` for those features until the next release.
+> source/backend support, VS Code Copilot transcript harvesting, or multi-skill
+> fan-out and subset adoption; use a source install from `main` for those
+> features until the next release.
 
 ## Training
 
@@ -144,11 +145,25 @@ Actions are `run`, `dry-run`, `status`, `adopt`, `harvest`, `schedule`, and
 | `--lookback-hours N` | Initial transcript lookback; `0` scans all history |
 | `--max-sessions N` / `--max-tasks N` | Bound the harvested workload |
 | `--target-skill-path PATH` | Explicit skill document to stage/adopt |
+| `--skill-root PATH` | Add a skill-resolution root; repeatable, with relative paths resolved below `--project` |
 | `--tasks-file PATH` | Replay a reviewed task JSON file instead of harvesting |
 | `--edit-budget N` | Maximum bounded edits for the night |
 | `--progress` / `--json` | Progress or machine-readable output |
 | `--auto-adopt` | Apply an accepted staged proposal automatically |
 
+`adopt` also accepts `--skill NAME` (repeatable) and `--all-skills` for a night
+that staged per-skill proposals. Use `--legacy` to adopt only a co-staged
+managed `SKILL.md` / `CLAUDE.md` proposal. Bare `adopt` on a fan-out night lists
+the names and exits instead of promoting anything. A leading-dash name must use
+the unambiguous `--skill=--name` form. See
+[multi-skill staging](../sleep/multi-skill-staging.md).
+
+Fan-out resolves existing project-native `.agents/skills`, `.claude/skills`,
+`.cursor/skills`, and `.devin/skills` directories plus the established Claude
+roots. Use `--skill-root` for another integration-specific location. Configure
+the canonical `multi_skill_fanout` key to enable proposal fan-out;
+`multi_skill_report` remains a compatibility alias.
+
 The `mock` and `handoff` backends make no network calls. A real backend sends
 mining, replay, judging, and reflection prompts derived from harvested
 transcripts and tasks to its selected provider. Review that provider's

docs/sleep/README.md

@@ -100,16 +100,18 @@ pip install skillopt        # installs the engine + the `skillopt-sleep` command
 skillopt-sleep dry-run      # harvest + mine + replay, report only; stages nothing
 skillopt-sleep run          # a full nightly cycle; the proposal is staged for review
 skillopt-sleep status       # show state + the latest staged proposal
-skillopt-sleep adopt        # apply the latest staged proposal
+skillopt-sleep adopt --legacy       # apply a reviewed managed proposal
+skillopt-sleep adopt --skill NAME   # adopt one staged skill (repeatable)
+skillopt-sleep adopt --all-skills   # adopt every still-pending fan-out skill
 skillopt-sleep schedule     # install a nightly cron entry for this project
 ```
 
 > **Version note.** This page tracks `main`. PyPI 0.2.0 provides the base
 > commands above. Cursor source/backend/plugin support, VS Code Copilot
 > transcript harvesting, Pi source/backend support, Sleep handoff, non-Azure
 > OpenAI-compatible endpoints, OpenCode Sleep source/backend support, and
-> `--preferences` landed later and require a source install from `main` until
-> the next release.
+> `--preferences`, multi-skill fan-out, and reviewed subset adoption landed
+> later and require a source install from `main` until the next release.
 
 The per-agent integrations below still come from the repo; the CLI above is the
 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
 Deterministic proof (no API key):
 `python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves`.
 
-### Opt-in: per-skill group reporting
+### Opt-in: per-skill fan-out
 
-Set `"multi_skill_report": true` in `~/.skillopt-sleep/config.json` to add an
-independent gate result and report row for every explicit skill hint mined that
-night:
+Set `"multi_skill_fanout": true` in `~/.skillopt-sleep/config.json` to add an
+independent gate result and reviewable proposal for every explicit skill hint
+mined that night. `multi_skill_report` remains a compatibility alias:
 
 ```json
-{"multi_skill_report": true}
+{"multi_skill_fanout": true}
 ```
 
 This runs one additional consolidation per group (including a catch-all group when
-hinted and unhinted evidence are mixed), so it increases backend calls and token use.
-It is reporting-only for now: every group starts from the same managed skill
-document, and Sleep does not yet resolve and update several live `SKILL.md` files
-automatically. Nights containing only the managed catch-all group keep the existing
-single-consolidation behavior.
+hinted and unhinted evidence are mixed), so it multiplies backend calls and token
+use; configured dream rollouts and synthetic variants multiply the per-group work
+too. Each group inherits the configured edit budget, gate mode/metric,
+`gate_no_regression`, `dream_rollouts`, `dream_factor`, `recall_k`, and
+`evolve_skill`. Recalled archive tasks are restricted to that same skill hint;
+shared memory is read-only in fan-out runs. Setting `evolve_skill` to `false`
+therefore disables per-skill proposals as well as the managed skill proposal.
+
+Each explicitly hinted group resolves and reads its own live `SKILL.md` before
+consolidation, so its staged proposal preserves that skill's baseline. Missing,
+ambiguous, unreadable, aliased, or colliding skills are skipped and reported
+instead of falling back to the managed document. Adoption remains review-driven:
+choose fan-out proposals with `adopt --skill NAME` or `--all-skills`, and use
+`adopt --legacy` for a co-staged managed skill/memory pair. `auto_adopt` never
+promotes the per-skill fan-out. Nights containing only the managed catch-all group
+keep the existing single-consolidation behavior.
+
+Resolution searches existing project-native `.agents/skills`, `.claude/skills`,
+`.cursor/skills`, and `.devin/skills` directories, then the established Claude
+home and plugin-cache roots. Add repeatable `--skill-root PATH` values when an
+integration stores skills elsewhere. Relative roots resolve below `--project`.
 
 ### Opt-in: experience replay & dream rollouts
 
@@ -363,6 +381,13 @@ gate keeps the worst case bounded; keep it **on** by default.
 
 ## Learn more
 
+The **low-level** API for staging one proposal per skill and adopting a reviewed
+subset (`staged_skills` / `adopt_skills`, plus `status` and `adopt --skill`) is
+documented in [`docs/sleep/multi-skill-staging.md`](multi-skill-staging.md).
+That page also documents the opt-in nightly fan-out, where every hinted group
+derives its proposal from its own resolved live `SKILL.md` while adoption remains
+an explicit human decision.
+
 See the [SkillOpt documentation index](../index.md), the
 [CLI reference](../reference/cli.md), and the integration-specific READMEs under
 [`plugins/`](https://github.com/microsoft/SkillOpt/tree/main/plugins).