@rhize/skill-forge 0.8.0 → 0.10.0

package/LICENSE

@@ -19,6 +19,13 @@ Pro Modules
 - src/provenance.ts
 - src/queue.ts
 - src/evolve.ts
+- 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

@@ -70,6 +70,16 @@ skill-forge add <source> [options]             Quarantine-install a skill and ru
 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 audit [options]                    Doctor-style health check over the configured skill/MCP set (alias: doctor)
+skill-forge organize [options]                 Set-level capability registry + dependency graph across configured skills roots (Pro)
+skill-forge find [query] [options]             Discover skills via skills.sh and check partner security audits (free)
+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
 ```
@@ -280,6 +290,232 @@ in place of `ingest-prompt.md`. `--yes` (and `init --defaults`, which passes it
 implies either — a non-interactive run writes only the report and, if a profile was already
 stored, the config; nothing else.
 
+### `organize` (v0.9, Pro)
+
+```bash
+skill-forge organize
+skill-forge organize --json
+skill-forge organize --out ./registry.json
+skill-forge organize --usage-snapshot ./skill-monitor-snapshot.json
+```
+
+Pro (free during the 0.x beta). Builds a set-level view across every configured `skillsRoots`
+entry: a **capability registry** (per-skill row — `tier`/`domain`/`consumes`/`provenance`/
+`maturity` frontmatter, plus untagged/rot flags) and a **dependency graph** (nodes, `consumes`
+edges, orphans, hot resources, dangling edges, cycles). This is the TS port of the plugin's
+`index_skills.py` + `build_dependency_graph.py`, merged into one command — graph nodes are keyed
+by realpath-qualified stable IDs (not bare frontmatter names), so duplicate names across roots
+don't collapse adjacency; duplicate-name ambiguity and unresolved `consumes` targets are reported
+rather than silently dropped.
+
+| Option | Effect |
+|---|---|
+| `--json` | Print the registry + graph as JSON instead of the terminal summary. |
+| `--out <file>` | Write the full report JSON to this path. Refuses an existing path (`wx`, `0o600` — same discipline as `audit --report`). |
+| `--usage-snapshot <file>` | Join per-skill usage counts from a skill-monitor snapshot JSON (`usage_joined` in the output); a zero-match snapshot is warned about, not silently ignored. |
+
+`organize` performs its own self-contained scan — it does not reuse `audit`'s inventory walker
+— and, like every other command, never executes anything found under a scanned skills root.
+
+### `find` (v0.9, free)
+
+```bash
+skill-forge find "pdf form filling"
+skill-forge find "pdf form filling" --limit 20 --json
+skill-forge find --audit owner/skill-name
+skill-forge find --get owner/skill-name
+skill-forge find --curated
+```
+
+Free. TS port of the plugin's `skills_sh.py` — discovery only, exactly one mode per invocation
+(search, `--audit`, `--get`, or `--curated`; mutually exclusive):
+
+| Mode | Effect |
+|---|---|
+| `<query>` (default) | Search skills.sh; each result shows id, install count, and the install hint `skill-forge add <id>` — **not** `npx skills add`, since `add` runs the full local quarantine/gate. |
+| `--audit <id>` | Partner security-audit verdicts (Socket, Snyk, Gen Agent Trust Hub, …) for a specific skills.sh id — pass/warn/fail + risk. No auto-audit of search results. |
+| `--get <id>` | Detail + file tree for a specific skills.sh id. |
+| `--curated` | List skills.sh's curated skills. |
+| `--limit <n>` | Max search results (default 10). |
+| `--json` | Print the raw API payload as JSON. |
+
+Search results are labeled **unvetted** — `find` never installs or gates anything itself. Think
+of `find --audit` as the partner-verdict layer and `add`/`scan` as the deep local gate; they're
+two independent checks, not a replacement for one another.
+
+**Auth: `VERCEL_OIDC_TOKEN`.** All requests are HTTPS GETs to `https://skills.sh/api/v1`, using a
+bearer token read from `process.env.VERCEL_OIDC_TOKEN` — never stored in config, never printed.
+Without it, `find` fails loud (exit code 3) with setup guidance:
+
+```
+1. skills.sh authenticates with a short-lived Vercel OIDC token
+2. npm i -g vercel && vercel link && vercel env pull   (writes VERCEL_OIDC_TOKEN to .env.local)
+3. export VERCEL_OIDC_TOKEN from .env.local into your shell before running this command
+   (or set it directly: export VERCEL_OIDC_TOKEN=...)   —   docs: https://skills.sh/docs/api
+```
+
+Note step 3: `vercel env pull` writes the token into `.env.local`, it does not export it into your
+shell — you (or your shell's dotenv loader) still need to export it before `find` can see it.
+
+### `watch` (v0.9, Pro)
+
+```bash
+skill-forge watch
+skill-forge watch --offline
+skill-forge watch --json
+```
+
+Pro (free during the 0.x beta). TS port of the plugin's `record_provenance.py --check-drift`.
+Scans **every** configured `skillsRoots` entry's `SOURCES.md` provenance ledger (deduped by
+realpath, each reported row names its ledger) and reports, per tracked entry, whether the
+recorded upstream ref still matches what the source currently resolves to.
+
+For entries whose `Source` parses as a git URL and whose `Upstream ref` looks like a commit/tag,
+`watch` runs a fixed, first-party `git ls-remote <url> [ref]` (argv array, no shell) to compare —
+`--offline` skips all network checks and just lists entries for manual comparison. Every other
+entry is listed for manual checking regardless.
+
+**`watch` NEVER executes a ledger's stored drift-check command string.** That string is
+attacker-influenceable data — anyone who can write to a skills root's `SOURCES.md` controls it.
+It is only ever printed, sanitized, as a suggestion for you (or an agent) to run yourself.
+
+### `ingest` + `queue close` (v0.9, Pro)
+
+```bash
+skill-forge ingest
+skill-forge ingest --list
+skill-forge ingest --list --json
+skill-forge queue close <id> --status ingested
+skill-forge queue close <id> --status dismissed
+```
+
+Pro (free during the 0.x beta). The queue-drain UX that previously only existed as the
+`rhize-meta` plugin's `/rhize-meta:forge-ingest` slash command. `ingest` (no args) validates every
+pending `~/.skill-forge/queue.json` entry — each entry's `quarantinePath`/`installedPath` must
+canonicalize under the configured quarantine dir or a configured skills root/MCP target;
+mismatched or escaping entries are reported and excluded — then hands the surviving summary off to
+the configured coding agent (same handoff plumbing as `add --ingest`) with `assets/ingest-prompt.md`,
+which now carries the full queue-drain workflow. `--list` is read-only: it prints pending entries
+(`--json` for machine-readable output) without any handoff.
+
+For a single new source, use `skill-forge add <source> --ingest` instead — that runs the full
+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
@@ -396,7 +632,11 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | `evolve` — SkillOpt-Sleep self-evolution, re-gating, provenance, queueing (v0.7) | | ✓ |
 | `audit` — inventory, hygiene findings, report, business profile, foundation scaffold (v0.8) | ✓ | ✓ |
 | `audit`'s cross-root overlap clusters (v0.8) | | ✓ |
-| Set-level organizer (capability registry, redundancy, dependency graph) | | ✓ |
+| `organize` — set-level capability registry + dependency graph (v0.9) | | ✓ |
+| `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
@@ -448,9 +688,14 @@ implementation status.
 that deeper judgment (which patterns to keep, whether to absorb into an existing skill vs. fork a
 new one, verifying the result beats baseline) is a job for a coding agent, not the gate. `--ingest`
 hands a promoted skill off to one, running the bundled, agent-neutral prompt at
-`assets/ingest-prompt.md` (Claude Code users get a deeper experience via the companion
-`rhize-skill-forge` plugin skill, but the bundled prompt works with any agent). The same flag works
-on an MCP server promote (`--artifact mcp --ingest`, v0.6): the bundled prompt branches on the
+`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. 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.
 
@@ -530,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.