@rhize/skill-forge 0.9.0 → 0.11.0

package/LICENSE

@@ -22,6 +22,11 @@ Pro Modules
 - src/organize.ts
 - src/commands/watch.ts
 - src/commands/ingest.ts
+- src/commands/routine.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,16 +75,28 @@ 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 rollback <backup-id>        Restore a promotion backup (Pro)
+skill-forge refine which <skill>               Print override-resolution order for a skill
+skill-forge routine [options]                  One scheduled maintenance pass: audit + drift + registry, cron-friendly (Pro)
+skill-forge promote <id> [options]             Re-gate a held quarantine entry and promote it
+skill-forge reject <id> [options]              Discard a held quarantine entry
+skill-forge config <sub> [args]                Read/write open-ended preferences (list|get|set|unset|propose|review)
 skill-forge list                               List skills currently held in quarantine
 skill-forge status                             Show configuration and quarantine summary
+skill-forge guide [topic]                      Orientation: what this does, your current state, the next command
 ```
 
 ### `init`
 
 ```bash
 skill-forge init              # interactive: pick targets, default target, handoff agent
-skill-forge init --defaults   # non-interactive: all detected agents, first as default (CI)
+skill-forge init --defaults   # non-interactive: agents found on PATH, first as default (CI)
 skill-forge init --list       # print detected agent skill roots and exit — no writes
+skill-forge init --all-agents # don't narrow to agents whose CLI is on PATH — keep every root
 ```
 
 Probes the known agent matrix (`src/agents.ts`) for both project-relative (`.claude/skills`, ...)
@@ -95,6 +107,40 @@ 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).
 
+**Menus are keyed on the PATH, not the agent (v0.11).** Many agents share one skills directory —
+18 entries in the agent matrix use `.agents/skills` as their project root — so the gate-target and
+default-target menus list each *distinct* root once, labelled with the agents that resolve to it
+(`19 agents (project): Amp, Replit, Universal, +16 more`), and `skillsRoots`/`mcpTargets` are
+written deduped. `config.agents` still records every agent, since it's an id→root map. Detection
+output says so explicitly when roots collapse (`→ 21 agents share 3 distinct skills root(s)`).
+Configs written by earlier versions are deduped on load, so no re-run is required to clean one up.
+
+**Narrowed to agents you actually have (v0.11).** Because a shared directory can't tell you which
+of its 18 agents you use, init also checks PATH: a root is pre-selected when at least one agent
+mapped to it has its CLI installed, and roots with none are still listed, just switched off with
+the reason shown.
+
+```
+[x] 1. /Users/you/.agents/skills
+       on PATH: Codex, Gemini CLI (project) (+17 other agents share this path)
+[ ] 3. /Users/you/.openclaw/skills
+       OpenClaw (global) — no verified CLI name to check
+```
+
+The PATH check is a **look-up only — nothing found is ever executed** (no `--version` probe), and
+binary names are held to the same evidence bar as the skill paths: an agent with no verified
+command name reports "unknown", never "not installed". `--all-agents` turns narrowing off, and it
+disables itself automatically if no agent CLI is found at all, so it can never reduce a working
+detection to an empty config. The handoff menu is only *reordered* by it — installed CLIs float to
+the top and everything detected stays pickable.
+
+**Selecting things (v0.11).** The multi-selects take a whole answer at once — `2`, `1 3`, `2, 4`,
+`2-5`, plus `all` and `none` — and Enter confirms. Anything unrecognized is named back to you and
+ignored, never silently swallowed. The single-choice prompts (default target, handoff agent)
+**re-ask** on an answer that isn't one listed number instead of falling back to option 1, so a
+multi-value or mistyped answer can no longer write a target you didn't choose. Ctrl+D at any
+prompt exits cleanly.
+
 **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,
@@ -384,9 +430,8 @@ 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
+Pro (free during the 0.x beta). The queue-drain UX for pending ingestions. `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`,
@@ -399,12 +444,247 @@ 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 [--status <s>] [--skill <s>] [--project <p>]
+skill-forge refine patterns [--status tracking|ready|generalized|dismissed] [--skill <s>]
+skill-forge refine promote <PATTERN-ID> [--dry-run] [--force] [--user-root <dir>]
+skill-forge refine rollback <backup-id> [--force]
+skill-forge refine which <skill> [--user-root <dir>]
+```
+
+Pro (free during the 0.x beta). Captures, applies, and generalizes improvements to installed
+skills from real usage feedback (see [CLAUDE.md's "refine (v0.10)" section](CLAUDE.md) for the
+full architecture 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** (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. Both `refine
+which` and `refine promote` accept `--user-root <dir>` to override the detected user-scope skills
+root (default: the first configured `skillsRoots` entry outside the current working directory,
+falling back to `~/.claude/skills`) — useful when the config's default root doesn't match the
+skill you're targeting.
+
+**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 <text> --content-file <file> --expected --actual
+--example --outcome --root-cause --pattern-id --scope <local|shared> --dry-run --json --yes
+--handoff`. `--content` takes override content inline; `--content-file <file>` reads it from a
+file instead (mutually exclusive with `--content`) — use it for anything multi-line rather than
+fighting shell quoting. 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
+bundled `assets/refine-prompt.md` carries the gap-analysis rubric (category/override-type decision
+tables, guided-mode triggers), 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.** `~/.claude/skill-refinements/` is a legacy
+location some users may have from earlier tooling — three flat markdown notes, no structured
+ledgers, no schema — and 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). Markdown ledgers like
+`refinement-history/*.md`, `aggregated-patterns.md`, or `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, so 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.
+
+### `routine` (v0.11, Pro)
+
+```bash
+skill-forge routine                       # audit + drift + registry, one report, writes nothing else
+skill-forge routine --json --offline      # for a scheduler: one JSON document, no network
+skill-forge routine --fail-on high        # exit 1 when a high/critical finding exists
+skill-forge routine --housekeeping        # opt in to bounded writes (see below)
+```
+
+The whole maintenance pipeline in one command, shaped for cron. Every other command answers one
+question; keeping a set healthy means running four and correlating them by hand, which is exactly
+what nobody does on a schedule. `routine` runs the audit, drift, and registry **engines**,
+correlates them into one report and one summary, and exits with a code a scheduler can alert on.
+
+**Non-interactive by construction** — it never prompts, so it cannot hang a scheduled job. It is
+also the only schedulable command that writes, so what it may write is fenced:
+
+| | writes |
+|---|---|
+| always | the combined report + `audit-state.json`, both under `~/.skill-forge` |
+| `--housekeeping` | prunes quarantine sandboxes older than `--prune-days` (default 30); closes queue entries whose skill is gone from disk |
+| `--handoff` | launches your configured agent with the curation prompt |
+
+Housekeeping and handoff are **opt-in**: a bare `skill-forge routine` in a crontab reports and
+nothing else. A step that was requested but could not run — a crashed drift check, a failed
+prune, an unreadable queue — is listed under **Incomplete steps** and **always exits nonzero**,
+independent of `--fail-on`: `--fail-on` grades what the audit *found*, whereas a degraded run
+means the routine did not do what was scheduled, and a cron job that exits 0 on that is blind. Pruning only ever deletes inside the quarantine dir — never a skills root — is
+age-bounded, `--dry-run`-able, and lists every path in the report. A queue entry is only closed
+when the skill it points at no longer exists; a pending entry whose skill is still installed is
+undone work, not an orphan. `routine` never installs, promotes, or rejects: no candidate enters a
+skills root without a human or agent decision, and a cron job is not that.
+
+```
+0 9 * * 1  skill-forge routine --offline --fail-on high --housekeeping
+```
+
+### `promote <id>` / `reject <id>` (v0.11)
+
+Answering **hold** at the gate used to be a dead end: the sandbox sat in quarantine and no command
+could ever finish the decision. These close that loop.
+
+```bash
+skill-forge promote <id>          # re-gate the held sandbox, then promote/hold/reject
+skill-forge reject <id>           # discard it
+```
+
+Works for both artifact types: a held MCP candidate is re-gated as an MCP server and written into
+your MCP config (`--mcp-target`), with env values emptied and unpinned `npx` specs pinned, exactly
+as `add --artifact mcp` would.
+
+`promote` **re-gates** rather than promoting blind. The original run's gate result was never
+persisted, so the alternative would be a queue entry with a fabricated gate record — and a hold
+may be days old, with the ruleset and your installed set since changed. Re-scanning is static and
+cheap. Ids come from `skill-forge list`; anything that resolves outside your quarantine dir
+(traversal, absolute path, symlink) is refused.
+
+### `config` (v0.11)
+
+`businessProfile` is five fixed fields, so anything else learned about you has nowhere to live.
+Preferences are open-ended key/value facts that accumulate without a schema change:
+
+```bash
+skill-forge config set prefers-typescript "strict mode, no any"
+skill-forge config list
+skill-forge config review
+```
+
+**Agents get a different door.** `set` is for a human at a keyboard and takes effect immediately;
+`propose` only ever queues something for review:
+
+```bash
+skill-forge config propose deploys-on vercel --origin "ingest agent" --note "seen in 3 skills"
+```
+
+An agent draining the queue reads untrusted skill content, so anything it concludes about you is
+downstream of text an attacker may have written. If agents could write preferences directly, a
+malicious `SKILL.md` could talk one into persisting an instruction into your config, where every
+later run would read it back as *your stated preference* — a durable prompt-injection foothold
+with a laundering step in the middle. Routing agent writes through review means the worst case is
+a proposal you decline. `review` is interactive, or takes an explicit `--accept-all`/`--reject-all`;
+it refuses to fall through to a default in a non-interactive shell.
+
+Both doors run the same validation: kebab-case keys, a length cap, no control characters, and a
+refusal for anything credential-shaped — by key name (`api-key`, `*-token`) or by value shape
+(`sk-…`, `ghp_…`, `AKIA…`, PEM blocks, JWTs). `config.json` is plain text; secrets belong in your
+keychain. Hand-edited entries that fail those checks are dropped on load rather than rendered.
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
 promoted or rejected). `status` shows the resolved configuration (skills roots, quarantine dir,
 strictness) plus a count of held entries.
 
+### `guide` (v0.11)
+
+```bash
+skill-forge guide            # what this does, where you are, what to run next
+skill-forge guide verbs      # a single topic
+```
+
+Orientation for someone — or some agent — dropping into an existing session. `--help` lists flags
+but can't tell you what to do with them, and `status` prints configuration without saying what it
+means; `guide` answers "what is my current state, and what is the next command". It reads your
+config, quarantine, and queue and names one next step, unfinished work first: nothing configured →
+`init`; entries awaiting a decide-pass verb → `ingest`; candidates still held → `list`; no audit
+ever run → `audit`.
+
+```
+Where you are:
+  config:      /Users/you/.skill-forge/config.json
+  gate targets: 3 (default: /Users/you/.agents/skills)
+  quarantined: 2
+  queue:       12 pending
+
+Suggested next step:
+  skill-forge ingest
+  12 promoted items still awaiting a decide-pass verb
+```
+
+Topics: `pipeline`, `verbs`, `queue`, `mcp`, `refine`, `maintenance`, `pro`. **Read-only and
+non-interactive** — it writes nothing and never prompts, so it's safe to run inside an agent turn,
+and with no config it says so rather than reciting default placeholder paths as if they were
+settings.
+
 ## MCP gating (v0.5)
 
 `add` and `scan` can also gate an **MCP server** instead of a skill — the same quarantine →
@@ -519,6 +799,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
@@ -570,11 +851,9 @@ 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` — 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).)
+`assets/ingest-prompt.md` — works with any agent. ABSORB extractions from an ingest pass route
+through `skill-forge refine` in this same package — 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 +934,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.