feat(sleep): adopt reviewed skill subsets safely

[Bogdan (Dan) Baciu (bogdanbaciu21)]

Summary

Supersedes #189, which could not be reopened after its branch was rebased.

Adds an explicit, auditable way to adopt a reviewed subset of multi-skill Sleep proposals. Staging remains non-mutating: live skills change only when adopt_skills() is explicitly called.

What changed

• Adds staged_skills() to inspect staged skill proposals.
• Adds adopt_skills(staging_dir, skill_names) for subset or all-skill adoption.
• Validates every selection before writing anything.
• Backs up existing files and replaces them atomically.
• Rolls back the entire selection if any write fails.
• Records SHA-256 before/after hashes and backup paths.
• Preserves existing file permissions.
• Documents the staging layout, adoption flow, receipts, and migration behavior.

Safety contract

• No implicit adoption.
• Unknown, duplicate, malformed, or unsafe selections fail before writes.
• Unselected skills remain untouched.
• Partial adoption cannot survive a failed write.
• Every adopted change produces a verifiable receipt.

Compatibility

The existing single-skill path is unchanged:

• Manifests without skills remain valid.
• adopt() retains its current behavior.
• adopt_skills() is an independent, opt-in API.
• skill_names=None adopts all staged skills; [] adopts none.

Review follow-up

Addresses all feedback from #189:

• Validates the manifest root.
• Rejects unsafe proposal filenames.
• Preserves file modes during atomic replacement.
• Removes the redundant live-file read.

Validation

• 39 focused tests passed.
• 233 Sleep tests passed, 3 skipped.
• 945 full-suite tests passed, 8 skipped.
• Ruff passed.

Non-goals

• Automatic adoption.
• Changes to gate or scoring behavior.
• Changes to legacy single-skill staging semantics.

[Yifan Yang (Yif-Yang)]

Thanks for working on a safer reviewed-skill adoption flow. The staging/adoption primitives are a useful foundation, but the user-facing workflow is not connected end to end yet.

Before merging, could you please:

• Connect run_sleep_cycle → SkillProposal → write_staging, then provide a CLI flow that lists staged skills and lets the user adopt a selected subset.
• Add a cycle-level integration test where more than one skill is proposed, all proposals are staged, and only the selected subset is promoted.
• Update the documentation so it clearly distinguishes the low-level adoption API added here from an end-to-end multi-skill nightly workflow; the latter is not yet available in the current implementation.
• Revalidate manifest uniqueness and live-target nonexistence at adoption time, rather than relying only on staging-time checks.
• Preserve transactionality if updating adopted_skills.json fails: any live skill files written by that adoption should be rolled back as well.

Once the workflow and these safety edges are covered, we would be happy to re-review it.

[Bogdan (Dan) Baciu (bogdanbaciu21)]

Absolutely. On it.

[Bogdan (Dan) Baciu (bogdanbaciu21)]

Yifan – five items from your review are in this push.

Cycle now stages accepted skills that resolve uniquely. skillopt-sleep status lists them. adopt --skill NAME (repeatable) or --all-skills promotes the reviewed subset. Bare adopt on a multi-skill night lists the names and exits instead of promoting everything. Unresolved, empty, or colliding names skip the night instead of aborting it.

There is a cycle-level test that stages two live skills and adopts one. Only that live file changes.

Docs now split the low-level adopt API (this PR) from a full multi-skill nightly workflow. The latter is still not this PR: groups still consolidate from the managed document.

Adopt re-checks uniqueness against every staged row, not just the selection. If the receipt write fails, the live files from that adoption and the previous adopted_skills.json roll back.

I also tightened adopt itself: staged files are sha256-pinned, live writes refuse symlink targets and symlink parents and will not create parent directories, and empty bodies are refused.

Proof on f393a7a: full pytest 982 passed, 7 skipped. Ready for re-review.