@rhize/skill-forge 0.8.0 → 0.9.0

package/LICENSE

@@ -19,6 +19,9 @@ Pro Modules
 - src/provenance.ts
 - src/queue.ts
 - src/evolve.ts
+- src/organize.ts
+- src/commands/watch.ts
+- src/commands/ingest.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,11 @@ 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 list                               List skills currently held in quarantine
 skill-forge status                             Show configuration and quarantine summary
 ```
@@ -280,6 +285,120 @@ 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).
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
@@ -396,7 +515,10 @@ 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) | | ✓ |
 
 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 +570,12 @@ 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. 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).)
+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.