@rhize/skill-forge 0.6.0 → 0.7.0

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
@@ -161,13 +225,15 @@ guessing between the two).
 |---|---|---|
 | Local directory | `./my-mcp-server` | Copied into quarantine, same as a local skill source. |
 | Git URL | `https://github.com/owner/mcp-server.git` | Shallow-cloned into quarantine, same as a git skill source. |
-| npm package | `@scope/name` or `some-mcp-server` | `npm pack <name> --pack-destination <quarantine>`, then tarball **extraction only** — never `npm install`, never lifecycle scripts. |
+| npm package | `@scope/name` or `some-mcp-server` | `npm pack <name> --ignore-scripts --pack-destination <quarantine>`, then tarball **extraction only** — never `npm install`, never lifecycle scripts. Every tarball member path is validated (absolute paths and `..` segments are rejected) before extraction. |
 
 **What's gated**
 
 Safety runs the same built-in deny-pattern ruleset used for skills (curl\|bash, credential-file
-access, etc.) plus MCP-specific rules: inline credential values in config/env, unpinned `npx -y`
-launch commands, `--dangerously-*`/`--no-sandbox` flags, and filesystem-root launch args — see the
+access, etc.) plus MCP-specific rules: inline credential values in config/env (quoted or
+unquoted), unpinned `npx -y` launch commands (a moving/dist tag like `@latest` counts as
+unpinned, and `npx` is recognized by basename so a full path or `npx.cmd` can't evade it),
+`--dangerously-*`/`--no-sandbox` flags, and filesystem-root launch args — see the
 [MCP safety ruleset table](docs/gate-policy.md#mcp-safety-ruleset). Overlap analysis (Pro, free
 during the 0.x beta) ranks the candidate against the server entries already present in your
 configured `mcpTargets` files, instead of against a skills root.
@@ -235,6 +301,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
@@ -266,6 +333,11 @@ implementation status.
 - **Block on HIGH/CRITICAL.** Any finding at `HIGH` or `CRITICAL` severity blocks the candidate
   outright (verdict `block`); a lower-severity finding produces `warn`; a clean scan is `pass`.
   `--yes` honors this: `block` is rejected automatically.
+- **npm-sourced MCP candidates: `--ignore-scripts` + tarball member validation.** An npm-package
+  MCP source is fetched with `npm pack --ignore-scripts`, and the tarball's member list is checked
+  with `tar -tzf` before extraction — any absolute path or `..` path segment refuses the extract
+  with an error instead of running `tar -xzf` (a path-traversal guard against a malicious tarball
+  writing outside the quarantine sandbox).
 - **SkillSpector, when installed.** If [SkillSpector](https://github.com/NVIDIA/SkillSpector)
   (Apache-2.0) is on `PATH`, skill-forge shells out to it (`--no-llm` by default, so scanned skill
   content is never sent to an external LLM provider) and merges its findings into the same report.