@rhize/skill-forge 0.7.0 → 0.8.0

package/README.md

@@ -69,6 +69,7 @@ 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 list                               List skills currently held in quarantine
 skill-forge status                             Show configuration and quarantine summary
 ```
@@ -89,6 +90,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 +204,82 @@ 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.
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
@@ -270,6 +354,14 @@ map — it never touches a skills root:
 - **Missing target file/parent dirs:** created.
 - A candidate config listing more than one server gates/promotes the first (same "N found — using
   the first" convention `add`/`scan` already use for a multi-skill source), noted on stderr.
+- **Version pinning is enforced, including on a candidate's own documented entry (v0.7).** A
+  candidate's `.mcp.json` server entry is used for `command`/`args` when present, but an unpinned
+  `npx` spec there (`"args": ["-y", "pkg@latest"]`) is no longer written through as-is: it's
+  **auto-pinned** to `<package>@<version>` when it matches the version skill-forge scanned from the
+  candidate's own (self-declared) `package.json`, or **promotion is refused** (with an explanation
+  and no override flag) when it can't be safely auto-pinned — a different package name, no version
+  found, or a more complex shape (e.g. a `-p`/`--package` dependency, or more than one spec).
+  See [docs/gate-policy.md](docs/gate-policy.md#mcp-promote-version-pin-enforcement-v07).
 
 There's no MCP equivalent of the skill provenance ledger (`SOURCES.md`) — the pending-ingestion
 queue (Pro) and `--ingest` handoff both apply the same way, keyed on the written config file path
@@ -302,6 +394,8 @@ 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) | | ✓ |
+| `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) | | ✓ |
 
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit