@rhize/skill-forge 0.7.1 → 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

@@ -69,6 +69,12 @@ skill-forge init [options]                     Detect installed agents and set g
 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 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
 ```
@@ -89,6 +95,13 @@ overwrites the fields it's responsible for. If no `config.json` exists yet, `add
 `status` offer to run this for you on first use (skipped entirely for `--json`/`--yes`/non-TTY
 invocations, so scripted runs never block on a prompt).
 
+**Init now ends by offering the audit (v0.8).** After an interactive run writes its config, it
+asks "Run the skills & MCP audit now? [Y/n]" (default yes) and, if accepted, runs
+`skill-forge audit` interactively — see [`audit`](#audit-v08) below. `init --defaults` runs it too,
+but non-interactively (`--yes`): a report is written, with no business-profile prompt, no
+foundation scaffold, and no agent handoff. `init --list` and an aborted/empty selection stay
+write-free, so neither writes a config nor runs the audit.
+
 ### `add`
 
 ```bash
@@ -196,6 +209,196 @@ adopting, `evolve` refuses (unless `--force`) when the staged proposal is alread
 the live skill it would replace, since that's the signature of a staging dir that was already
 adopted once.
 
+### `audit` (v0.8)
+
+```bash
+skill-forge audit
+skill-forge doctor                          # alias
+skill-forge audit --json --report ./audit.md
+skill-forge audit --yes
+skill-forge audit --foundation
+skill-forge audit --handoff
+```
+
+A re-runnable, doctor-style health check over the skill/MCP set you've **already** configured —
+unlike `add`/`scan`, which gate a new candidate before it's installed, `audit` inventories what's
+already there and looks for hygiene issues and consolidation/refinement opportunities. Requires a
+real, saved config (`skill-forge init` first) — it never silently audits an invented default.
+`init` now ends by offering to run it (see [`init`](#init) above); it's equally safe to run any
+time on its own.
+
+| Option | Effect |
+|---|---|
+| *(none)* | Interactive: offers to capture/reuse a business profile, then runs the audit, then offers the foundation scaffold and agent handoff. |
+| `--json` | Prints the full audit report as JSON instead of the terminal summary. Non-interactive — skips the business-profile prompt. |
+| `-y, --yes` | Skips every interactive prompt (business profile, foundation, handoff). Never implies `--foundation` or `--handoff`. |
+| `--report <file>` | Write the report here instead of the default `~/.skill-forge/reports/audit-<ISO-timestamp>.md`. Refuses an existing path — never overwrites. |
+| `--foundation` | The one skills-root write this command can make: scaffold a `business-foundation` skill from the captured business profile (see below). |
+| `--handoff` | Hand the written report off to your configured coding agent with the bundled curation prompt, via the same handoff plumbing as `add --ingest`. |
+
+**What it inventories/checks.** Every configured `skillsRoots` entry — symlink-aware, deduped by
+realpath so a skill reachable via two roots or an aliased symlink is reported once, with alias
+locations kept rather than dropped. Per skill: strict frontmatter validation (a missing/unclosed
+fence or missing `name`/`description` is a finding, not silently backfilled), `SKILL.md` size and
+an estimated token count, and a full `scanSafety` pass — the same safety ruleset `add`/`scan` run.
+Every configured `mcpTargets` file: JSON targets get full server enumeration (name, command
+basename, package spec, arg/env **counts** — never values); TOML targets (e.g. Codex CLI's
+`config.toml`) get the same textual MCP safety scan `--artifact mcp` uses, since there's no
+structured TOML enumeration. A per-item failure (unreadable skill, broken symlink, malformed MCP
+config) becomes a finding — it never aborts the run.
+
+**Opportunity pass.** Beyond hygiene, the report surfaces:
+
+- **Overlap clusters** (Pro, free during the 0.x beta) — cross-root overlap scoring across every
+  inventoried skill, grouped into connected components, each with a top pairwise score and a
+  suggested verb code (`ABSORB`/`FORK`/`DEFER` — `opportunities.overlapLocked` in `--json` output
+  says whether this ran or was Pro-locked, without string-matching `notices`). The fuller
+  five-verb matrix (adding `REJECT`/`WATCH`) belongs to the agent-side curation prompt's deeper
+  decide pass (`--handoff`), not this report. Locked → that section shows the standard upgrade
+  notice and empty clusters; everything else in the report still runs.
+- **Evolve-eligible skills** — structurally valid, safety-passing skills, labeled as eligible for
+  `skill-forge evolve` — an eligibility list, not a judgment that they need refining.
+- **A business-foundation opportunity** — offered whenever `config.foundationSkillPath` isn't set
+  yet.
+
+**Business profile.** Interactive runs (never under `--yes`/`--json`/non-TTY) open with a
+business-name/industry/audiences/workflows/constraints Q&A, preceded by an explicit "don't enter
+credentials or confidential customer data" warning. An existing stored profile is offered for
+reuse rather than re-asked, and a fresh capture is shown back as a summary before it's saved to
+`config.businessProfile`. This profile grounds both the foundation scaffold and the curation
+handoff prompt.
+
+**Report location + privacy.** Written to `~/.skill-forge/reports/audit-<ISO-timestamp>.md` by
+default (`--report <file>` to override), created with `{ flag: 'wx', mode: 0o600 }` — exclusive
+create (refuses to overwrite an existing report) and owner-only permissions. MCP `env` values and
+arbitrary arg values are never written into the report or the `--json` payload — only server/
+command names, package specs, and counts.
+
+**Explicit opt-ins.** `--foundation` is the *only* way this command writes to a skills root: it
+scaffolds `<targetRoot>/business-foundation/SKILL.md` from the captured business profile
+(containment-checked against `config.skillsRoots`, refuses an existing or symlinked destination,
+writes atomically, and runs `scanSafety` on the generated content before it's placed), then
+records the path to `config.foundationSkillPath`. `--handoff` is the *only* way this command
+launches an agent — same argv-array, no-shell discipline as `--ingest` (see
+[Ingestion handoff](#ingestion-handoff---ingest)), using the bundled `assets/curation-prompt.md`
+in place of `ingest-prompt.md`. `--yes` (and `init --defaults`, which passes it through) never
+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
@@ -310,7 +513,12 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | 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) | | ✓ |
+| `audit` — inventory, hygiene findings, report, business profile, foundation scaffold (v0.8) | ✓ | ✓ |
+| `audit`'s cross-root overlap clusters (v0.8) | | ✓ |
+| `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
@@ -362,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.