@rhize/skill-forge 0.6.1 → 0.7.1

package/LICENSE

@@ -18,6 +18,7 @@ Pro Modules
 - src/gate/mcpOverlap.ts
 - src/provenance.ts
 - src/queue.ts
+- src/evolve.ts
 
 ...and the portions of built artifacts (e.g. dist/cli.js in the published npm
 package) generated from these files. Each Pro Module carries a header

package/README.md

@@ -65,11 +65,12 @@ anything ending in `.git`), or a local filesystem path.
 ## Commands
 
 ```
-skill-forge init [options]             Detect installed agents and set gate targets / handoff agent
-skill-forge add <source> [options]     Quarantine-install a skill and run it through the gate
-skill-forge scan <source> [options]    Gate a skill without installing it (always cleans up)
-skill-forge list                       List skills currently held in quarantine
-skill-forge status                     Show configuration and quarantine summary
+skill-forge init [options]                     Detect installed agents and set gate targets / handoff agent
+skill-forge add <source> [options]             Quarantine-install a skill and run it through the gate
+skill-forge scan <source> [options]            Gate a skill without installing it (always cleans up)
+skill-forge evolve <skill-dir> [options]       Self-evolve an installed skill via SkillOpt-Sleep, re-gate, decide (Pro)
+skill-forge list                               List skills currently held in quarantine
+skill-forge status                             Show configuration and quarantine summary
 ```
 
 ### `init`
@@ -132,6 +133,69 @@ anything — the quarantine sandbox is always cleaned up afterward, on success o
 nonzero when the safety verdict is `block`. `--json` prints the same gate-result payload shape as
 `add`'s.
 
+### `evolve` (v0.7)
+
+```bash
+skill-forge evolve .claude/skills/my-skill
+skill-forge evolve .claude/skills/my-skill --yes
+skill-forge evolve .claude/skills/my-skill --dry-run
+skill-forge evolve .claude/skills/my-skill --backend claude --yes
+```
+
+Pro (free during the 0.x beta). Orchestrates [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)'s
+`skillopt-sleep` CLI (`pip install skillopt`) to propose a self-evolution of an already-installed
+skill — harvest recent sessions, generate a candidate replacement `SKILL.md`/`CLAUDE.md`, and stage
+it — then runs the **staged proposal**, never the live skill, back through skill-forge's own static
+safety ruleset before you decide anything. SkillOpt-Sleep's own validation gate is score-only; it
+never content-vets the generated markdown. This closes that gap.
+
+| Option | Effect |
+|---|---|
+| `--project <dir>` | Project dir passed to SkillOpt-Sleep as `--project`. Defaults to cwd. |
+| `--dry-run` | Uses SkillOpt-Sleep's `dry-run` subcommand — report only, nothing staged. |
+| `--backend <name>` | SkillOpt-Sleep backend. Defaults to `mock` (offline, deterministic, no network). |
+| `--lookback-hours <n>` | Hours of session history for SkillOpt-Sleep to harvest. |
+| `-y, --yes` | Skips interactive prompts (the disclosure confirm below, and the promote/hold/reject prompt) and honors the re-gate verdict automatically. |
+| `--json` | Prints the re-gate result as JSON instead of the terminal report. Implies non-interactive, same as `add`'s `--json`. |
+| `--force` | Allows re-adopting a staging dir whose proposed content already matches the live skill (see the double-adopt guard below). |
+
+**Requires `skillopt-sleep` on PATH** — skill-forge never installs it for you. If it's missing,
+`evolve` prints `pip install skillopt` + a docs pointer and exits, rather than attempting an
+auto-install (the same "detect, don't install" discipline the rest of the gate follows).
+
+**Data boundary.** The default `mock` backend is fully offline — harvesting and proposal
+generation both run locally, no session data leaves the machine. Any other backend (`claude`,
+`codex`, `azure_openai`, ...) sends truncated excerpts from harvested sessions and derived tasks to
+the provider you selected; per SkillOpt-Sleep's own docs this is not currently guaranteed to be
+secret-free. `evolve` prints that disclosure and requires either `--yes` or an interactive `y/N`
+confirmation before a non-`mock` run proceeds — `--json` is non-interactive, so a non-`mock` run
+under `--json` without `--yes` is refused rather than silently sending data off-machine.
+
+**Re-gate.** SkillOpt-Sleep only ever *stages* a proposal (`<project>/.skillopt-sleep/staging/<timestamp>/`
+— full replacement files, never auto-adopted). `evolve` copies just `proposed_SKILL.md` (and
+`proposed_CLAUDE.md`, if present) into a fresh temporary directory and runs skill-forge's own
+static safety ruleset over that copy — the same one `add`/`scan` use, at your configured
+`strictness`. `report.json`/`diagnostics.json` (SkillOpt-Sleep's own redacted holdout evidence) are
+never scanned. The result renders through the same terminal report / `--json` shape as `add`/`scan`.
+
+**Decision.** Same promote/hold/reject semantics as `add`: `--yes`/`--json` honor the re-gate
+verdict (a `block` is rejected); otherwise you're prompted.
+
+- **promote** — runs SkillOpt-Sleep's own `adopt --staging <dir>` (which backs up the live file(s)
+  before copying the proposal over them), then records a provenance entry to the target skill's
+  `SOURCES.md` and a pending-ingestion queue entry (`origin: "evolve"`, see
+  [docs/queue-schema.md](docs/queue-schema.md)) so a later ingest pass reviews the evolution rather
+  than an external source.
+- **hold** — leaves the staging dir exactly as SkillOpt-Sleep produced it (its own `status` command
+  still lists it); `report.md` has the full evidence.
+- **reject** — deletes the staging dir.
+
+**Double-adopt guard.** SkillOpt-Sleep's `adopt` has no confirmation of its own, and adopting the
+same staging dir twice overwrites *its* backup — the pre-evolution original would be lost. Before
+adopting, `evolve` refuses (unless `--force`) when the staged proposal is already byte-identical to
+the live skill it would replace, since that's the signature of a staging dir that was already
+adopted once.
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
@@ -206,6 +270,14 @@ map — it never touches a skills root:
 - **Missing target file/parent dirs:** created.
 - A candidate config listing more than one server gates/promotes the first (same "N found — using
   the first" convention `add`/`scan` already use for a multi-skill source), noted on stderr.
+- **Version pinning is enforced, including on a candidate's own documented entry (v0.7).** A
+  candidate's `.mcp.json` server entry is used for `command`/`args` when present, but an unpinned
+  `npx` spec there (`"args": ["-y", "pkg@latest"]`) is no longer written through as-is: it's
+  **auto-pinned** to `<package>@<version>` when it matches the version skill-forge scanned from the
+  candidate's own (self-declared) `package.json`, or **promotion is refused** (with an explanation
+  and no override flag) when it can't be safely auto-pinned — a different package name, no version
+  found, or a more complex shape (e.g. a `-p`/`--package` dependency, or more than one spec).
+  See [docs/gate-policy.md](docs/gate-policy.md#mcp-promote-version-pin-enforcement-v07).
 
 There's no MCP equivalent of the skill provenance ledger (`SOURCES.md`) — the pending-ingestion
 queue (Pro) and `--ingest` handoff both apply the same way, keyed on the written config file path
@@ -237,6 +309,7 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | Overlap analysis against your configured skill set | | ✓ |
 | Provenance ledger (`SOURCES.md` audit trail) | | ✓ |
 | Pending-ingestion queue + `--ingest` handoff | | ✓ |
+| `evolve` — SkillOpt-Sleep self-evolution, re-gating, provenance, queueing (v0.7) | | ✓ |
 | Set-level organizer (capability registry, redundancy, dependency graph) | | ✓ |
 
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit