diff --git a/plugins/disk-hygiene/.claude-plugin/plugin.json b/plugins/disk-hygiene/.claude-plugin/plugin.json index 812d3ce51..6f01e8c62 100644 --- a/plugins/disk-hygiene/.claude-plugin/plugin.json +++ b/plugins/disk-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "disk-hygiene", - "version": "0.3.0", + "version": "0.4.0", "description": "Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content, changed entries, and live-handle uncertainty fail closed.", "author": { "name": "Melodic Software", diff --git a/plugins/disk-hygiene/CHANGELOG.md b/plugins/disk-hygiene/CHANGELOG.md index bdc16b741..42ad3ba28 100644 --- a/plugins/disk-hygiene/CHANGELOG.md +++ b/plugins/disk-hygiene/CHANGELOG.md @@ -3,6 +3,18 @@ All notable changes to the `disk-hygiene` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.4.0] + +### Added + +- **`/disk-hygiene:setup` skill on the uniform contract** (fleet conformance + wave, dim 8). `check` reads the clean skill's bundled scripts as the source + of truth and probes Python 3.11+, conditional Git, the current OS family's + documented lane (Linux `lsof` and macOS audit-only reported as INFO), and + the effective `disk_hygiene_enabled` toggle. `apply` is guidance-only with + no write path; toggle guidance states `--config`'s fresh-install-only + semantics. A disabled toggle downgrades prerequisite FAILs to INFO. + ## [0.3.0] Fixes driven by a live Windows user-profile audit where the engine was unusable through its diff --git a/plugins/disk-hygiene/README.md b/plugins/disk-hygiene/README.md index 2a0eab755..2f7db65b0 100644 --- a/plugins/disk-hygiene/README.md +++ b/plugins/disk-hygiene/README.md @@ -57,6 +57,9 @@ at preview. Backups remain the recovery boundary for user data. - macOS supports audit/report only because this implementation has no authoritative bind-mount and descriptor-anchoring proof for its execution lane. +Verify this machine's prerequisites and platform posture with `/disk-hygiene:setup check`; +`/disk-hygiene:setup apply` resolves anything the check reports with guidance. + ## Usage ```text diff --git a/plugins/disk-hygiene/skills/setup/SKILL.md b/plugins/disk-hygiene/skills/setup/SKILL.md new file mode 100644 index 000000000..980e40c72 --- /dev/null +++ b/plugins/disk-hygiene/skills/setup/SKILL.md @@ -0,0 +1,68 @@ +--- +name: setup +description: "Verify the disk-hygiene plugin's runtime prerequisites and platform posture for this machine. Use when: 'set up disk-hygiene', 'configure disk-hygiene', 'is disk-hygiene working', a clean run reported a missing prerequisite, or before a first audit on a new machine. Actions: check (read-only verification, default) | apply (resolve what check found). Re-runnable and safe." +argument-hint: "check | apply" +user-invocable: true +disable-model-invocation: true +--- + +## Purpose + +Thin check-centric setup per the uniform contract: `check` inspects and reports, `apply` +resolves. This plugin owns no consumer-project configuration — targets and modes arrive as +`/disk-hygiene:clean` arguments, and the only tunable is the native `userConfig` toggle — +so `apply` is pure guidance and writes nothing. + +Action routing: no argument or `check` runs the check; `apply` runs the check first, then +points at each remediation. Both are non-interactive — never prompt when the action is given. + +## `check` (read-only) + +The clean skill and its bundled scripts (`${CLAUDE_PLUGIN_ROOT}/skills/clean/`) are the +single source of truth for what the plugin requires per platform. **Read them first** — +probe what they actually require, don't recite this file. Then run each probe via Bash and +report a PASS/FAIL/INFO table with one remediation line per FAIL. + +When the plugin's toggle is disabled, every prerequisite absence downgrades from FAIL to +INFO — a deliberately disabled plugin is not broken. Report the probes informationally and +note that re-enabling restores the FAIL semantics. + +1. **Python 3.11+ on `PATH`** — the interpreter used by scanning, validation, the + skill-scoped guard, and cleanup. FAIL if absent or older, with the README's requirement + as the remediation; the plugin never downloads a runtime. Report the absolute + interpreter path (guarded engine calls must use the same absolute interpreter the guard + reports — Bash aliases and functions cannot substitute). +2. **Git** — `command -v git`. Conditional per the README: optional for ordinary trees, + required when a target contains or sits inside a Git worktree. Report presence as INFO + with that conditionality stated; absence is only a FAIL for worktree-containing targets. +3. **Platform posture** — detect the current OS family and report its documented lane per + the README: Windows (full, `lstat` reparse + Win32, never UAC), Linux (full when + `/proc/self/mountinfo` is readable; `lsof` needed only for the optional execution + lane — absent `lsof` is INFO with the reduced-capability note), macOS (audit/report + only by design — INFO, not a defect). +4. **Hook toggle** — report the effective `disk_hygiene_enabled` value: + `${user_config.disk_hygiene_enabled}` (unexpanded or empty means default `true`). +5. **Plugin registration** — INFO: confirm the plugin is enabled for this project + (`/plugin` → Installed) rather than parsing settings files. + +## `apply` (idempotent) + +Run `check`, then for each FAIL point at the resolution. Every prerequisite is a system +tool or an OS capability, so `apply` installs nothing and writes nothing — it only points: + +- missing/old Python: the platform's own Python 3.11+ install channel; never a plugin + download. +- missing git (worktree targets): platform install instructions. +- toggle off: direct to `/plugin configure disk-hygiene` (interactive, any time). + Headless: `--config` only applies on a fresh install (ignored once installed), so + reconfigure via `claude plugin uninstall disk-hygiene` then + `claude plugin install disk-hygiene@ --config disk_hygiene_enabled=true`; + this skill never writes user settings or `pluginConfigs`. + +Re-running `apply` after everything passes changes nothing and reports "already configured". + +## What this skill does NOT do + +- Run an audit or cleanup — that is `/disk-hygiene:clean`. +- Write the plugin cache, Claude Code user settings, or `pluginConfigs`. +- Install any tool or runtime, during either `check` or `apply` — guidance only. diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json index dfb052526..c18ec5e87 100644 --- a/plugins/guardrails/.claude-plugin/plugin.json +++ b/plugins/guardrails/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "guardrails", - "version": "0.6.2", + "version": "0.7.0", "description": "Eight safety guards that block secret/credential writes, hardcoded machine-specific paths, git hook-bypass attempts, irreversible git operations (force-push, reset --hard, worktree-wide checkout/restore discards), Bash file-write workarounds that circumvent Write/Edit hooks, (advisory) hallucinated CLI flags, (advisory) un-throttled Workflow fan-out that risks burst 529s, and (advisory) direct git commit/gh pr create calls bypassing this marketplace's own commit/pull-request skills — each independently toggleable.", "author": { "name": "Melodic Software", diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index bddfefb31..a303dd52c 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to the `guardrails` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.7.0] + +### Added + +- **`/guardrails:setup` skill on the uniform contract** (fleet conformance + wave, dim 8). `check` reads the guard scripts and `hooks.json` as the + source of truth and probes Bash 5.0+, `jq` (absence = every guard fails + open — surfaced as the FAIL it is), each guard's effective toggle, the + `cli-flag-verify` scan surface, and the `block-dangerous-git` allowlist. + `apply` is guidance-only with no write path; reconfiguration guidance + states `--config`'s fresh-install-only semantics. All-toggles-disabled + downgrades prerequisite FAILs to INFO. + ## [0.6.2] ### Changed diff --git a/plugins/guardrails/README.md b/plugins/guardrails/README.md index ff9679d39..b3ed5928a 100644 --- a/plugins/guardrails/README.md +++ b/plugins/guardrails/README.md @@ -146,6 +146,10 @@ as before. /plugin install guardrails@melodic-software ``` +Then verify the runtime prerequisites and live guard surface with +`/guardrails:setup check`; `/guardrails:setup apply` resolves anything the +check reports with guidance. + ## License MIT (SPDX-License-Identifier: MIT). See the `LICENSE` file at the root of the diff --git a/plugins/guardrails/skills/setup/SKILL.md b/plugins/guardrails/skills/setup/SKILL.md new file mode 100644 index 000000000..2b39843e5 --- /dev/null +++ b/plugins/guardrails/skills/setup/SKILL.md @@ -0,0 +1,69 @@ +--- +name: setup +description: "Verify the guardrails hooks' runtime prerequisites and per-guard toggle state for this machine. Use when: 'set up guardrails', 'configure guardrails', 'is guardrails working', 'which guards are on', a guard failed open with a jq notice, or after tuning guard toggles. Actions: check (read-only verification, default) | apply (resolve what check found). Re-runnable and safe." +argument-hint: "check | apply" +user-invocable: true +disable-model-invocation: true +--- + +## Purpose + +Thin check-centric setup per the uniform contract: `check` inspects and reports, `apply` +resolves. This plugin owns no consumer-project configuration — every tunable is a native +`userConfig` option (eight per-guard toggles plus the `cli_flag_verify_bins`, +`cli_flag_verify_skip_bins`, and `block_dangerous_git_allow` scalars) — so `apply` is pure +guidance and writes nothing. + +Action routing: no argument or `check` runs the check; `apply` runs the check first, then +points at each remediation. Both are non-interactive — never prompt when the action is given. + +## `check` (read-only) + +The guard scripts (`${CLAUDE_PLUGIN_ROOT}/hooks/*.sh`) and `hooks.json` are the single +source of truth for the guard inventory and each guard's runtime needs. **Read them +first** — probe what they actually require, don't recite this file. Then run each probe +via Bash and report a PASS/FAIL/INFO table with one remediation line per FAIL. + +When every guard's toggle is disabled, prerequisite absences downgrade from FAIL to INFO — +a deliberately disabled plugin is not broken. Report the probes informationally and note +that re-enabling restores the FAIL semantics. + +1. **Bash 5.0+** — the guards' documented runtime floor (Git Bash on native Windows). + FAIL below the floor with the README Requirements remediation. +2. **`jq`** — `command -v jq`. FAIL if absent: per the README, every guard then fails + OPEN (disabled) with a one-line stderr notice — the machine is unguarded, which is + exactly what this check exists to surface. +3. **Per-guard toggles** — report each guard's effective value from its + `${user_config._enabled}` rendering (unexpanded or empty means default `true`), + one row per guard, so the user sees the live guard surface at a glance. +4. **`cli-flag-verify` scan surface** — report the effective `cli_flag_verify_bins` / + `cli_flag_verify_skip_bins` values and INFO-note the guard's own behavior for scanned + binaries missing from `PATH` (skipped, never flagged — per the guard source). +5. **`block-dangerous-git` allowlist** — report the effective `block_dangerous_git_allow` + value (patterns only, verbatim; it contains no secrets by design). +6. **Hook registration** — INFO: confirm the plugin is enabled for this project + (`/plugin` → Installed) rather than parsing settings files. + +## `apply` (idempotent) + +Run `check`, then for each FAIL point at the resolution. Every prerequisite is a system +tool and every tunable is native `userConfig`, so `apply` installs nothing and writes +nothing — it only points: + +- missing `jq` / old Bash: platform install instructions from the README Requirements + section; this skill never installs system packages. +- any toggle or scalar change: direct to `/plugin configure guardrails` (interactive, any + time). Headless: `--config` only applies on a fresh install (ignored once installed), so + reconfigure via `claude plugin uninstall guardrails` then + `claude plugin install guardrails@ --config KEY=VALUE …` (repeatable); + this skill never writes user settings or `pluginConfigs`. + +Re-running `apply` after everything passes changes nothing and reports "already configured". + +## What this skill does NOT do + +- Exercise a guard — any matching tool call does that end-to-end. +- Write the plugin cache, Claude Code user settings, or `pluginConfigs`. +- Install any tool, during either `check` or `apply` — guidance only. +- Weaken a guard: it reports and routes; disabling is always the user's explicit act + through the native configuration surface. diff --git a/plugins/review/.claude-plugin/plugin.json b/plugins/review/.claude-plugin/plugin.json index c9a4b54cd..45496c6e4 100644 --- a/plugins/review/.claude-plugin/plugin.json +++ b/plugins/review/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "review", - "version": "0.13.0", + "version": "0.14.0", "description": "Code-review toolkit: six read-only reviewer agents (code, security, architecture, doc drift, build/test/lint, CI-log audit) plus two orchestration skills — a single-lens quality gate and a multi-surface review fan-out with severity-ranked, deduplicated findings.", "author": { "name": "Melodic Software", diff --git a/plugins/review/CHANGELOG.md b/plugins/review/CHANGELOG.md index 596dcfc6f..78ea0ab5c 100644 --- a/plugins/review/CHANGELOG.md +++ b/plugins/review/CHANGELOG.md @@ -3,6 +3,19 @@ All notable changes to the `review` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.14.0] + +### Changed + +- **Setup adopts the uniform check/apply contract** (fleet conformance wave, + dim 8 — caught by the new contract gate rather than the wave list). `check` + runs the standards-contract binding's state-reading procedure read-only + (index presence, row-path validation, version delta) and reports; `apply` + carries the existing bootstrap/reconfigure/migration flow with its + explicit-confirmation gates intact, re-verifying after every write. The + by-reference discipline is unchanged — the procedure still lives in the + contract binding, not restated here. + ## [0.13.0] ### Changed diff --git a/plugins/review/skills/setup/SKILL.md b/plugins/review/skills/setup/SKILL.md index 5eb4edb4a..d5d8a5672 100644 --- a/plugins/review/skills/setup/SKILL.md +++ b/plugins/review/skills/setup/SKILL.md @@ -1,7 +1,7 @@ --- name: setup -description: "Configure the review plugin for this repository: bootstrap the consumer's standards index per the standards convention — the index review criteria resolve through — persisting docs/standards/ and, on relocation, .claude/standards.yaml. Use when: 'set up review', 'configure the review plugin', 'review setup', 'set up standards', 'bootstrap the standards index', or a review skill reports a missing or version-skewed standards index. Re-runnable — safe to invoke again to reconfigure or migrate." -argument-hint: "(no arguments — interactive interview)" +description: "Configure the review plugin for this repository: bootstrap the consumer's standards index per the standards convention — the index review criteria resolve through — persisting docs/standards/ and, on relocation, .claude/standards.yaml. Use when: 'set up review', 'configure the review plugin', 'review setup', 'set up standards', 'bootstrap the standards index', or a review skill reports a missing or version-skewed standards index. Actions: check (read-only verification, default) | apply (bootstrap, reconfigure, or migrate). Re-runnable." +argument-hint: "check | apply" user-invocable: true disable-model-invocation: true --- @@ -20,7 +20,16 @@ implement it by reference, do not restate it. Idempotent: re-running reads the current state and offers an update rather than overwriting blind; a re-run against a conforming, current-version index proposes no changes. -## Task +Action routing per the uniform contract: no argument or `check` runs the binding's state-reading +procedure read-only and reports — index presence and resolved standards root, per-row path +validation, and the DIRECTIONAL version delta — as a PASS/FAIL/INFO table with one remediation +line per FAIL, writing nothing. `apply` runs `check` first, then the binding's bootstrap / +reconfigure / migration flow below; after any write it re-runs the relevant probe and reports the +actual result. Non-interactive when the state admits exactly one conforming action (the +conforming-index short-circuit); the binding's explicit-confirmation gates (hand-authored README +conversion, bootstrap writes) remain explicit user decisions, never silent. + +## `apply` task Plugin-side notes on top of the binding's procedure: diff --git a/scripts/validate-plugin-contracts.mjs b/scripts/validate-plugin-contracts.mjs index 81f7bc3dc..90e4d2ec6 100755 --- a/scripts/validate-plugin-contracts.mjs +++ b/scripts/validate-plugin-contracts.mjs @@ -39,6 +39,19 @@ for (const path of setupSkills) { if (!/^disable-model-invocation:\s*true\s*$/m.test(frontmatter)) { fail(path, "setup skills must set disable-model-invocation: true"); } + // Uniform contract shape (PLUGIN-PHILOSOPHY "Setup is explicit and repeatable"): + // check is the default read-only action; apply exists unless the skill declares the + // userConfig-only check-only carve-out the doctrine sanctions. + if (!/^argument-hint:\s*"check(?:\s*\||\s*\[|")/m.test(frontmatter)) { + fail(path, 'setup skills must declare check as the leading action in argument-hint ("check", "check | apply ...", or "check []")'); + } + const body = content.slice(content.indexOf("---", 3) + 3); + if (!/`check`/.test(body)) { + fail(path, "setup skills must document the read-only check action"); + } + if (!/`apply`/.test(body) && !/check-only/i.test(body)) { + fail(path, "setup skills must document apply, or declare the check-only userConfig-only carve-out"); + } } const setupContractFiles = pluginFiles.filter(