@rhize/skill-forge 0.11.3 → 0.13.0

package/README.md

@@ -70,6 +70,9 @@ 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 finding accept <fp-prefix>         Acknowledge a LOW/MEDIUM audit finding you've reviewed (human-only, no gate effect)
+skill-forge finding revoke <fp-prefix>         Remove a stored acceptance so the finding reports again
+skill-forge finding list [options]             List every accepted finding
 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)
@@ -169,6 +172,18 @@ target skills root until you decide.
 | `-t, --target <dir>` | Skills root to promote into. Defaults to the config's `defaultTarget`, then `skillsRoots[0]`. |
 | `--json` | Prints the gate result (profile, safety findings, overlap) as JSON instead of the terminal report box. Implies non-interactive: the decision is made the same way `--yes` makes it (verdict decides promote/hold/reject), never an interactive prompt. |
 | `--ingest` | Pro (free during the 0.x beta). After a successful promote, hands off to a coding agent — see [Ingestion handoff](#ingestion-handoff---ingest). |
+| `--skill-map <path>` | Path to a generated `rhize-plugins` skill map (Phase 4 of that repo's skill-map-graph-substrate plan). When given, ranks the candidate's name/description against every `skill` node in the map — a near-duplicate of an already-shipped marketplace skill is folded into the safety findings as a `HIGH`-severity finding (escalates the verdict to `block`, so it's held rather than silently promoted); a moderate overlap is `MEDIUM` (`warn`). Free (not Pro-gated) — this enforces the marketplace's own curation rule ("close the gap, don't duplicate"), not a premium ranking feature. Missing/unreadable map: printed to stderr, never fatal. **Two map variants exist, with different coverage**: the **static** map (`rhize-plugins/generated/skill-map.static.json`) is first-party-only — it only knows about that marketplace's own skills, so it cannot catch a candidate that duplicates an *installed third-party plugin's* skill. The **resolved** map (`~/.claude/context-manager/skill-map.resolved.json`, produced by `rhize-context-manager`) additionally carries the full third-party ecosystem inventory. Point `--skill-map` at the resolved map when you want ecosystem-wide duplicate detection; the static map is enough only when you're curating a single first-party marketplace against itself. |
+
+**Bugfix (v0.13.0):** `--skill-map` previously matched nothing against either real map variant — the loader read a `type` field that the real generated artifact never sets (it uses `kind`), so every node was silently invisible to the overlap check. `loadSkillMap()` now normalizes `kind` → `type` at load time; regression coverage lives in `test/mapOverlap.realmap.test.ts` against vendored real-map snapshots. If you were relying on `--skill-map` before v0.13.0, it was a no-op — re-run `add`/`scan` on anything you're unsure about.
+
+**Extends-declared overlap exemption**: a candidate can declare `metadata.rhize.extends:
+["<skill-name>" | "<plugin>/<skill-name>"]` in its SKILL.md frontmatter to mark itself a
+deliberate specialization/layering of an existing map skill. When the top `--skill-map` match is
+a skill the candidate declares it extends, that finding is downgraded from a HOLD-level safety
+finding to an informational notice printed above the report — it never escalates the verdict.
+Overlap with any *other* skill (a different match, or a second candidate/skill pair) still holds
+at full severity: the exemption applies per declared pair, not globally, so declaring an
+extension of skill X never waives overlap with skill Y.
 
 A promoted skill gets a provenance entry appended to `<target>/SOURCES.md`, and every promote or
 hold decision is recorded to `~/.skill-forge/queue.json` (or `$SKILL_FORGE_HOME/queue.json`) — see
@@ -190,7 +205,7 @@ skill-forge scan owner/name --json
 Runs the same gate pipeline as `add` (profile → safety → overlap → report) but never promotes
 anything — the quarantine sandbox is always cleaned up afterward, on success or failure. Exits
 nonzero when the safety verdict is `block`. `--json` prints the same gate-result payload shape as
-`add`'s.
+`add`'s. Also accepts `--skill-map <path>` — see `add`'s option table above.
 
 ### `evolve` (v0.7)
 
@@ -293,6 +308,13 @@ basename, package spec, arg/env **counts** — never values); TOML targets (e.g.
 structured TOML enumeration. A per-item failure (unreadable skill, broken symlink, malformed MCP
 config) becomes a finding — it never aborts the run.
 
+**Accepted findings (v0.12).** Every finding in the report carries a fingerprint
+(`(fp a1b2c3d4e5f6)`); `Findings` shows **active** findings only, and a separate
+**Accepted findings** section lists whatever you've reviewed and accepted via
+[`skill-forge finding accept`](#finding-v012) — permanently, with reason and date, even after it
+stops matching (see that section for the full contract). `summary.acceptedCount` and each
+finding's `fingerprint` are additive `--json` fields; nothing accepted is ever silently deleted.
+
 **Opportunity pass.** Beyond hygiene, the report surfaces:
 
 - **Overlap clusters** (Pro, free during the 0.x beta) — cross-root overlap scoring across every
@@ -331,6 +353,49 @@ 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.
 
+### `finding` (v0.12)
+
+```bash
+skill-forge finding accept <fingerprint-prefix> --reason "Funnel genuinely needs root; verified"
+skill-forge finding revoke <fingerprint-prefix>
+skill-forge finding list [--stale] [--json]
+```
+
+Acknowledge an `audit` finding you've reviewed and accepted, so it stops counting against
+`routine --fail-on` and the `add`/`scan` advisory while staying **permanently visible** in its own
+report section — an audit you can't triage decays into noise, and noise is how the one real
+finding gets skimmed. Every finding in an `audit`/`routine` report now carries a 12-char
+fingerprint (`(fp a1b2c3d4e5f6)`) you copy into `accept`/`revoke`.
+
+| Command | Effect |
+|---|---|
+| `finding accept <fp-prefix> --reason <text>` | Records an acceptance. Re-runs the read-only audit engine to resolve the prefix against what's **currently active** — you can only accept a finding that exists right now, never from a stale report. `--reason` is mandatory (1-200 chars, no control characters). |
+| `finding revoke <fp-prefix>` | Removes a stored acceptance so the finding reports again. Resolves against the **store**, not a fresh audit run — the target may no longer be producible, which is exactly when you'd want to clean up. |
+| `finding list [--stale] [--json]` | Lists every accepted finding (severity, rule, target, reason, accepted date, fingerprint). `--stale` filters to records whose target no longer exists on disk. |
+
+**Identity is content-derived, not a name you pick.** A finding's fingerprint is
+`sha256(severity + rule + target + the offending line's text)` — deliberately excluding the LINE
+NUMBER (drifts on unrelated edits) and deliberately including SEVERITY (so a rule re-tuned to a
+higher severity for the same content can't inherit an ack minted against the lower one). Any change
+to the offending content **fails open to re-reporting** — this is the design, not a bug: the
+alternative (key on rule+path only) is the classic baseline trap, where accepting one benign line
+silently suppresses every future line the same rule matches in that file. Full contract, the
+per-rule `context` table, and fail-open read semantics: see
+[docs/accepted-findings-schema.md](docs/accepted-findings-schema.md).
+
+**Severity-capped, human-only, no override.** `finding accept` refuses `HIGH`/`CRITICAL` findings
+outright — there is no `--force`. The precision problem this command exists to solve lives at
+`LOW`/`MEDIUM`; a `HIGH` false positive is a rule bug to fix, not something to baseline. This is a
+human-door CLI (`config set` model), not the agent-facing propose/review queue — both
+`assets/ingest-prompt.md` and `assets/curation-prompt.md` instruct agents to never run
+`finding accept`/`finding revoke` themselves; an agent that judges a finding a false positive says
+so in its summary and lets the user run the command.
+
+**Never a gate input.** Acceptances only ever affect `audit`'s own report classification (and,
+downstream, `routine --fail-on` and the `add`/`scan` advisory) — `add`/`scan`/`promote <id>`/
+`evolve`'s re-gate never reads the accepted-findings store. See
+[docs/gate-policy.md](docs/gate-policy.md#accepted-findings-v012).
+
 ### `organize` (v0.9, Pro)
 
 ```bash
@@ -404,6 +469,7 @@ shell — you (or your shell's dotenv loader) still need to export it before `fi
 skill-forge watch
 skill-forge watch --offline
 skill-forge watch --json
+skill-forge watch --skill-map generated/skill-map.static.json
 ```
 
 Pro (free during the 0.x beta). TS port of the plugin's `record_provenance.py --check-drift`.
@@ -420,6 +486,45 @@ entry is listed for manual checking regardless.
 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.
 
+**`--skill-map <path>` (Phase 4 of `rhize-plugins`' skill-map-graph-substrate plan)** additionally
+drift-checks every `fork-of` edge in a generated skill map: for each edge it resolves the local
+`skill` node's `path`/`contentHash` and the upstream (`external`) node's `url`/`path`, fetches or
+reads the upstream content, and compares content hashes. Same never-execute posture as the ledger
+check above: nothing derived from the map — including a fork-of edge's own `driftCheck`
+metadata — is ever executed; only fetch/read/hash/compare. A missing/unreadable map is a warning,
+never fatal. A node's repo-relative `path` (e.g. `rhize-context-manager/skills/x/SKILL.md`) is
+resolved against cwd, the map's own directory, and that directory's parent (in that order) — not
+cwd alone — so `watch --skill-map <path>` gives correct verdicts regardless of the directory you
+run it from.
+
+**Verdict**, per fork-of edge — three-way comparison, four verdict states when both hashes below
+are present on the map, else the older two-way fallback (`in-sync`/`drifted`, `contentHash` vs
+freshly-fetched upstream):
+
+| local-normalized vs baseline | upstream-now vs baseline | status | actionable |
+|---|---|---|---|
+| == | == | `in-sync` | no |
+| != | == | `local-only` | no (deliberate fork divergence, e.g. Rhize's added frontmatter) |
+| == | != | `upstream-moved` | yes |
+| != | != | `diverged` | yes |
+
+The three-way matrix fires only when the local `skill` node carries `contentHashNormalized` (a
+hash of the file with Rhize-injected frontmatter stripped, computed once by the rhize-plugins
+compiler) **and** the upstream `external` node carries `baselineHash` (the upstream content hash
+as of the last human review, recorded in `rhize-plugins`' SOURCES.md and copied onto the node by
+that compiler — skill-forge never computes or fetches it itself). Either field missing on a given
+edge falls back to the two-way compare for that edge, so older maps keep working. All four
+three-way verdicts — `in-sync`, `local-only`, `upstream-moved`, and `diverged` — carry
+`baselineHash`/`upstreamHash` in the JSON output; the two-way-fallback rows and
+`upstream-unreachable`/`local-missing` never do (no verdict without a successful fetch/read, so
+there is nothing to compare against a baseline). Every row also carries an `actionable` boolean
+(from `isActionable`), so callers don't have to re-derive "needs attention" from `status`/`detail`
+prose — it's `true` for `drifted`, `upstream-moved`, `diverged`, `upstream-unreachable`, and
+`local-missing`; `false` for `in-sync` and `local-only`. **Re-baselining**: after reviewing and
+adopting an `upstream-moved`/`diverged` change, re-run `rhize-plugins`' `scripts/baseline_upstreams.py`
+and commit the updated SOURCES.md — that's the "I reviewed upstream, accept its state" action that
+clears the row back to `in-sync`/`local-only`.
+
 ### `ingest` + `queue close` (v0.9, Pro)
 
 ```bash
@@ -593,6 +698,13 @@ when the skill it points at no longer exists; a pending entry whose skill is sti
 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.
 
+**Accepted findings (v0.12)** are honored the same way `audit` honors them: `--fail-on` grades
+**active** findings only, so accepting every remaining finding via `skill-forge finding accept`
+turns a red `--fail-on any` green, and any new or changed finding turns it red again. A
+corrupt/missing accepted-findings store fails open (nothing gets suppressed) and surfaces as a
+report **notice**, never as an "Incomplete step" — see
+[docs/accepted-findings-schema.md](docs/accepted-findings-schema.md).
+
 ```
 0 9 * * 1  skill-forge routine --offline --fail-on high --housekeeping
 ```
@@ -720,9 +832,11 @@ guessing between the two).
 
 Safety runs the same built-in deny-pattern ruleset used for skills (curl\|bash, credential-file
 access, etc.) plus MCP-specific rules: inline credential values in config/env (quoted or
-unquoted), unpinned `npx -y` launch commands (a moving/dist tag like `@latest` counts as
-unpinned, and `npx` is recognized by basename so a full path or `npx.cmd` can't evade it),
-`--dangerously-*`/`--no-sandbox` flags, and filesystem-root launch args — see the
+unquoted), unpinned `npx` launch commands — MEDIUM with `-y`/`--yes` (silent install), **LOW
+without it (v0.12)**, since npx still prompts before the first install but the tag floats once
+cached (a moving/dist tag like `@latest` counts as unpinned either way, and `npx` is recognized by
+basename so a full path or `npx.cmd` can't evade it) — `--dangerously-*`/`--no-sandbox` flags, and
+filesystem-root launch args — see the
 [MCP safety ruleset table](docs/gate-policy.md#mcp-safety-ruleset). Overlap analysis (Pro, free
 during the 0.x beta) ranks the candidate against the server entries already present in your
 configured `mcpTargets` files, instead of against a skills root.
@@ -806,6 +920,7 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | `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) | | ✓ |
+| `finding accept`/`revoke`/`list` — acknowledge audit findings, never a gate input (v0.12) | ✓ | ✓ |
 
 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