@rhize/skill-forge 0.10.0 → 0.11.1

package/LICENSE

@@ -22,6 +22,7 @@ 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

package/README.md

@@ -79,17 +79,24 @@ skill-forge refine [options]                   Capture a project-scope override
 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`, ...)
@@ -100,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,
@@ -389,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`,
@@ -410,26 +450,23 @@ after its decide pass without hand-editing `queue.json` — writes are atomic (t
 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 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]
+skill-forge refine promote <PATTERN-ID> [--dry-run] [--force] [--user-root <dir>]
 skill-forge refine rollback <backup-id> [--force]
-skill-forge refine which <skill>
+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 — 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).
+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** (unchanged semantics from the plugin, configurable roots):
+**Override precedence** (configurable roots):
 
 ```
 1. PROJECT LOCAL   <cwd>/.claude/skills/<skill>/   highest
@@ -438,22 +475,29 @@ user-scope base skill is `refine promote`, and only against a `ready` pattern (o
 ```
 
 `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.
+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(-file) --expected --actual --example --outcome
---root-cause --pattern-id --scope <local|shared> --dry-run --json --yes`. All seven override types
+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 new
+**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 ported from the plugin's `analyze_gap.py`), the patch-action syntax,
-the pattern-fingerprint/generalization criteria, and the verification step. `refine --handoff`
+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`.
 
@@ -478,16 +522,16 @@ generalized only once the same gap recurs elsewhere. A `refine` patch on top of
 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
+**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. The plugin's two auto-trigger hooks ship here as documented templates instead:
+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
@@ -516,12 +560,137 @@ Control-char sanitization on every untrusted string that lands in human-readable
 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.
+
+Promotion also re-validates the candidate against the state it was gated in: each skill dir must
+still be a real directory rather than a symlink, no symlink inside it may resolve out of the
+sandbox, and its content digest must still match the one captured at gate time. Otherwise the gap
+between "scanned" and "installed" — days, for a hold — is a window in which vetted content can be
+swapped for something that never passed the gate.
+
+`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 →
@@ -688,13 +857,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. 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).)
+`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.