@rhize/skill-forge 0.9.0 → 0.10.0

package/LICENSE

@@ -22,6 +22,10 @@ Pro Modules
 - src/organize.ts
 - src/commands/watch.ts
 - src/commands/ingest.ts
+- src/refine/models.ts
+- src/refine/store.ts
+- src/refine/patch.ts
+- src/refine/context.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

@@ -75,6 +75,11 @@ skill-forge find [query] [options]             Discover skills via skills.sh and
 skill-forge watch [options]                    Drift check across every SOURCES.md provenance ledger (Pro)
 skill-forge ingest [options]                   Hand the pending-ingestion queue off to a coding agent for the decide/absorb pass (Pro)
 skill-forge queue close <id> --status <s>      Close a queue entry after the decide pass (Pro)
+skill-forge refine [options]                   Capture a project-scope override from real usage feedback (Pro)
+skill-forge refine list [options]              Show refinement history
+skill-forge refine patterns [options]          List tracked/ready/generalized/dismissed patterns
+skill-forge refine promote <PATTERN-ID>        Merge a ready pattern into the user-scope skill (Pro)
+skill-forge refine which <skill>               Print override-resolution order for a skill
 skill-forge list                               List skills currently held in quarantine
 skill-forge status                             Show configuration and quarantine summary
 ```
@@ -399,6 +404,118 @@ quarantine/gate pipeline first; `ingest` only ever drains what's already queued.
 `skill-forge queue close <id> --status ingested|dismissed` lets an agent close out a queue entry
 after its decide pass without hand-editing `queue.json` — writes are atomic (temp file + rename).
 
+### `refine` (v0.10, Pro)
+
+```bash
+skill-forge refine --skill my-skill --category hook --override-type patch \
+  --action insert-after --marker "Only check paths" \
+  --content "..." --expected "..." --actual "..." --dry-run
+skill-forge refine list [--skill <s>] [--project <p>]
+skill-forge refine patterns [--status tracking|ready|generalized|dismissed] [--skill <s>]
+skill-forge refine promote <PATTERN-ID> [--dry-run] [--force]
+skill-forge refine rollback <backup-id> [--force]
+skill-forge refine which <skill>
+```
+
+Pro (free during the 0.x beta). Captures, applies, and generalizes improvements to installed
+skills from real usage feedback — the npm-package absorption of what was previously the
+`rhize-plugins` repo's `rhize-meta` plugin `skill-refinement` skill (`/refine-skills`,
+`/review-patterns`, `/apply-generalization`); that plugin skill no longer exists (see
+[CLAUDE.md's "refine (v0.10)" section](CLAUDE.md) for the full merge notes, or
+`docs/refinement-schema.md` for the store shape).
+
+**Capture never mutates a base `SKILL.md`.** `refine` capture/apply writes ONLY project-scope
+override artifacts — `SKILL.patch.md` / `SKILL.extend.md` / `skill-config.json`, or a whole-file
+override copy for `full`/`hook`/`script` override types. The only command that ever touches a
+user-scope base skill is `refine promote`, and only against a `ready` pattern (or with `--force`).
+
+**Override precedence** (unchanged semantics from the plugin, configurable roots):
+
+```
+1. PROJECT LOCAL   <cwd>/.claude/skills/<skill>/   highest
+2. PROJECT SHARED  <cwd>/skills/<skill>/
+3. USER SCOPE      first configured skillsRoots entry outside cwd (fallback ~/.claude/skills)
+```
+
+`refine which <skill>` prints this resolution order and which override files exist at each scope —
+the "why didn't my patch take effect" debugging aid, made explicit and read-only.
+
+**Non-interactive capture contract.** Capture flags: `--skill --category --target --override-type
+<patch|extend|config|full|hook|script|new> --action <append|prepend|replace-section|insert-after|
+insert-before|delete-section> --marker --content(-file) --expected --actual --example --outcome
+--root-cause --pattern-id --scope <local|shared> --dry-run --json --yes`. All seven override types
+are supported: `patch`/`extend`/`config` are rendered from the flags; `full`/`hook`/`script` are
+verbatim override-file writes at project scope (content required); `new` creates an extension file
+for a capability that doesn't exist in the base skill yet. Always run `--dry-run` first and confirm
+the preview before writing for real — `--yes` skips re-prompting for a confirmation already given,
+it does not replace the dry-run preview.
+
+**The judgment step is the agent's job**, same pattern as `--ingest`/`audit --handoff`: a new
+bundled `assets/refine-prompt.md` carries the gap-analysis rubric (category/override-type decision
+tables, guided-mode triggers ported from the plugin's `analyze_gap.py`), the patch-action syntax,
+the pattern-fingerprint/generalization criteria, and the verification step. `refine --handoff`
+(opt-in) launches your configured agent with it, same handoff plumbing as `--ingest`; `--yes` never
+implies `--handoff`.
+
+**Pattern tracking and promotion.** A pattern becomes `ready` only when it recurs in a **second,
+genuinely different project** — repeat captures in the same project never flip it (occurrence
+`count` is derived from unique project identities, not raw refinement counts; see
+`docs/refinement-schema.md`). `refine patterns` lists tracked/ready/generalized/dismissed patterns,
+filterable by `--status --skill --project`. `refine promote <PATTERN-ID>` merges a `ready` pattern
+into the user-scope base skill: it backs up affected files first (manifest with per-file sha256 +
+original bytes + mode, tombstones for files that didn't exist), stages the write, validates, then
+renames into place — `--dry-run` previews the diff without writing, `refine rollback <backup-id>`
+restores from the manifest (refusing if current files have drifted since promote, unless
+`--force`). On promote, a `SOURCES.md` provenance entry is appended (verb `DEFER`, notes
+`"generalized from PAT-xxxx via skill-forge refine"`).
+
+**`evolve` vs. `refine`.** Both improve an already-installed skill, but at different scopes and
+triggers: `evolve` (v0.7) is *automated, whole-skill* optimization — it hands the entire skill off
+to SkillOpt-Sleep to propose a fresh replacement, re-gates the proposal, and lets you adopt or
+reject it wholesale. `refine` is *targeted, human/agent-driven* — it captures one specific observed
+gap ("expected X, got Y") and writes the smallest override that closes it, tracked and eventually
+generalized only once the same gap recurs elsewhere. A `refine` patch on top of an `evolve`d skill
+is fine; both record their own provenance entry, so the `SOURCES.md` ledger shows which change came
+from which mechanism.
+
+**Legacy store — deliberate skip, not a migration.** The plugin's `~/.claude/skill-refinements/`
+held three flat markdown notes (no structured ledgers, no schema) — there is no migration from it.
+Files there stay readable in place; if anything in them still matters, re-capture it via
+`skill-forge refine` against the greenfield JSON store described in
+[`docs/refinement-schema.md`](docs/refinement-schema.md). The plugin's markdown ledgers
+(`refinement-history/*.md`, `aggregated-patterns.md`, `generalization-queue.md`) are not
+recreated — JSON is the store; `refine list`/`refine patterns` are the human-readable view over it.
+
+**Auto-trigger hooks — templates, not automation.** A CLI cannot hook a running Claude Code
+session. The plugin's two auto-trigger hooks ship here as documented templates instead:
+`assets/hooks/refinement-detector.sh` (detects refinement-shaped language in a prompt) and
+`assets/hooks/session-end.sh` (prompts after a substantial session). Both are optional, inert if
+`skill-forge` isn't on `PATH`, and never call `skill-forge` themselves — they only print a
+suggestion. Wire either one in by adding it to your `.claude/settings.json` (or
+`~/.claude/settings.json`) hooks section — the exact snippet is in each script's own header
+comment:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "bash /path/to/refinement-detector.sh" }] }
+    ],
+    "SessionEnd": [
+      { "hooks": [{ "type": "command", "command": "bash /path/to/session-end.sh" }] }
+    ]
+  }
+}
+```
+
+**Security invariants** (same regime as v0.8/v0.9): nothing from a skill being refined is ever
+executed. Patch application writes ONLY under the resolved target scope dir for the named skill
+(containment-checked realpath, refuses a symlinked destination file); promotion writes ONLY under
+user scope, backup first. All child processes are argv arrays (git only, for context gathering).
+Control-char sanitization on every untrusted string that lands in human-readable output. `--yes`
+never implies `--handoff`. Applying a patch whose target `SKILL.md` is missing is refused; promoting
+a non-`ready` pattern without `--force` is refused.
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
@@ -519,6 +636,7 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | `find` — skills.sh discovery + partner audit verdicts (v0.9) | ✓ | ✓ |
 | `watch` — provenance drift check across every `SOURCES.md` ledger (v0.9) | | ✓ |
 | `ingest` + `queue close` — pending-queue drain handoff (v0.9) | | ✓ |
+| `refine` — capture/apply/generalize project-scope skill overrides (v0.10) | | ✓ |
 
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit
 promote/reject decision, with nothing held back. Pro is the curation layer on top: whether a new
@@ -573,8 +691,10 @@ hands a promoted skill off to one, running the bundled, agent-neutral prompt at
 `assets/ingest-prompt.md` — works with any agent. (As of v0.9, this fully replaces the `rhize-meta`
 plugin's `rhize-skill-forge` skill and its `/rhize-meta:forge-ingest`/`forge-scan`/`forge-watch`/
 `skill-find`/`skill-doctor` commands, which are removed; skill vetting/governance now lives
-entirely in this npm package. The plugin's remaining `skill-refinement` skill can still receive
-ABSORB extractions from an ingest pass — see [docs/forge-workflow.md](docs/forge-workflow.md).)
+entirely in this npm package. As of v0.10, the `rhize-meta` plugin's remaining `skill-refinement`
+skill is ALSO removed — ABSORB extractions from an ingest pass now route through
+`skill-forge refine` in this same package instead — see [`refine`](#refine-v010-pro) above and
+[docs/forge-workflow.md](docs/forge-workflow.md).)
 The same flag works on an MCP server promote (`--artifact mcp --ingest`, v0.6): the bundled prompt branches on the
 queue entry's `artifactType` and runs the matching decide pass — see
 [MCP gating](#mcp-gating-v05) above.
@@ -655,9 +775,9 @@ skill-forge is open-core with a split license (as of v0.2.0):
   safety gate, report, promote/hold/reject. See [LICENSE-MIT](LICENSE-MIT).
 - **Pro modules — Rhize Commercial License.** `src/license.ts`, `src/gate/overlap.ts`,
   `src/provenance.ts`, `src/queue.ts` (overlap analysis, provenance ledger, pending
-  queue / `--ingest` handoff). The source is available to read and audit, but production
-  use of Pro functionality requires a license key — see
-  [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
+  queue / `--ingest` handoff), and `src/refine/` (v0.10 — capture/apply/generalize skill
+  overrides). The source is available to read and audit, but production use of Pro
+  functionality requires a license key — see [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
 
 [LICENSE](LICENSE) is the authoritative map of which files fall under which license.
 Versions up to and including 0.1.0 were published entirely under MIT.