Use to run the Guardian sweep — a periodic read-only sweep of repo health (duplication, complexity, coupling, dependency and doc freshness, dead code). Reports maintainability drift since the last sweep as plain-language consequences; it never edits code or files issues. Not code review of a change (that is review-code).
Resources
1Install
npx skillscat add zwrose/superheroes/guardian Install via the SkillsCat registry.
This skill speaks in host-neutral actions. Resolve them to your runtime's tools by reading the host tool map at ${CLAUDE_PLUGIN_ROOT}/hosts/<your-host>-tools.md (the leading variable is this plugin's root directory) — claude-tools.md on Claude Code, codex-tools.md on Codex.
Guardian
Periodic read-only sweep of repo health. Deterministic collectors detect candidates; one model pass validates each against the project's declared conventions and writes plain-language consequences with receipts. Reports drift over a baseline — only what changed since the last sweep surfaces; settled trades stay suppressed. Per LEDGERS §2, the sweep never edits code, never commits or pushes, never files issues, and never runs or owns enforcement — it recommends; the advisor triages and consults the owner.
This skill is not /superheroes:review-code. Review-code finds bugs in a change; Guardian surfaces maintainability drift across the whole repo on a cadence.
Invocation
| Form | Behavior |
|---|---|
/superheroes:guardian |
Run a read-only repo-health sweep → drift report of plain-language consequences with receipts. Never edits, commits, or files. |
What a sweep is
- Collect (deterministic). Registered lenses run standard OSS collectors with thin normalization. Each lens diffs its digest against the prior snapshot and surfaces only new or worsened candidates. Red lines (absolute thresholds) bypass the baseline quiet rule. On a lens's first-ever baseline, candidates route through the same one model validation pass — high-precision lenses validate all candidates up to
firstBaselineValidateMax(default 10), volume lenses only up to that bound, with any remainder quiet-baselined and the skipped count disclosed; a collector-version re-baseline on an already-seeded lens stays quiet. - Validate (one model pass, inline). For each surfaced candidate, the running session validates against
CLAUDE.md,CONVENTIONS, the calibration profile, and any spec'd designs — killing unactionable ones (wrong context, sanctioned convention, test/generated code). Survivors get a one-sentence plain consequence, its receipt, and an effort estimate priced from measured evidence, never rule-catalog severity. - Finalize (deterministic). The sweep writes the report and compare-and-swap-replaces the drift baseline.
Drift-over-baseline. On a lens's first-ever baseline, high-precision lenses route candidates through validation (up to firstBaselineValidateMax, default 10); volume lenses validate only up to that bound and disclose the rest as baselined unreviewed; a collector-version re-baseline stays quiet. Later sweeps surface only what changed since the last snapshot.
Lens rollout. The health lenses (duplication, complexity, coupling, dependency and doc freshness, dead code) land across the guardian arc. The registered lenses today are duplication, hotspots, deps, deadcode, docs, and coupling (complexity/hotspots; deps covers dependency freshness + known vulnerabilities with check-the-check for a covering tool — Python advisories are severity-rated via osv-scanner so the critical-vuln red line covers Python, degrading to unrated pip-audit when the scanner is absent; deadcode runs vulture on Python + knip on Node for unused symbols, files, and exports — validated hard, since most hits are conventions the project sanctions on purpose; docs is stdlib-only and genuinely tool-free — it resolves the paths that root instruction docs and the calibrated verify command name, so a doc that points a future agent at a moved or deleted path surfaces, and it NEVER runs the verify command; coupling is a single lens covering JS/TS via dependency-cruiser and Python via an AST import census — data-only while declared-vocabulary reading is owner-deferred — so its baseline drift is counter-level (the couplingEdges vital on the snapshot), not edge-level: with vocabulary deferred the digest's eligible index is empty, so lens diff surfaces no edge drift until vocabulary reading is un-deferred); the remaining lenses land as their orders merge — a sweep today runs the registered lenses with first-baseline validation as above. Each later registration adds its lens name between the markers above and to guardian_lens.PRODUCTION_LENS_NAMES in the same PR; the roster sync guard fails closed if they drift.
Run it
The sweep runs in the advisor's own session, read-only. No external dispatch — the one model validation pass happens inline here.
1. Resolve + collect
Save the bundle JSON to a temp file. Sub-tools guardian_store.py paths and guardian_sweep.py verify-config are available when you need resolved artifact paths or fact verification.
ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
BUNDLE=$(mktemp /tmp/guardian-bundle-XXXXXXXX.json)
python3 -B "$ROOT_DIR/lib/guardian_sweep.py" collect --cwd . > "$BUNDLE"
cat "$BUNDLE" | jq .Optional — resolved storage paths (CONVENTIONS §2):
ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
python3 -B "$ROOT_DIR/lib/guardian_store.py" paths --cwd . | jq .Optional — trust-but-verify the four FACTS before validating:
ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
python3 -B "$ROOT_DIR/lib/guardian_sweep.py" verify-config --cwd . | jq .The bundle carries: surfaced (candidates needing validation), funnel, factVerdicts, ledgerStatus, redLines, lensMeta (per-lens validation guidance and consequence templates for surfaced lenses), and nextSnapshot (the staged baseline). Read ledgerStatus first — filed/tracked items are already dispositioned.
2. Validate (the one model pass)
For each entry in the bundle's surfaced list, validate the candidate:
- Read
bundle.lensMeta[<lens>].validationGuidancefor the lens-specific validation rubric, thenCLAUDE.md,CONVENTIONS.md, the calibration layers (core.md, plugin layers), and any relevant spec definition-docs. - Reject if unactionable: wrong context, sanctioned project convention, test/generated/boilerplate code, or already covered by a settled ledger trade.
- Validate survivors: draft exactly one plain sentence consequence (phrase it using
bundle.lensMeta[<lens>].consequenceTemplateas guidance), its receipt (the measured evidence), an effort estimate from that evidence (not rubric severity), and a ledgerJoin id (stable join key for the ledger).
Produce a dispositions JSON — exactly one entry per surfaced id:
[
{"id": "<surfaced-id>", "verdict": "validated", "consequence": "…", "receipt": "…", "effort": "…", "ledgerJoin": "…"},
{"id": "<surfaced-id>", "verdict": "rejected", "reason": "…"},
{"id": "<surfaced-id>", "verdict": "degraded", "reason": "…"}
]Verdicts: validated | rejected | degraded. A validated entry requires non-empty consequence, receipt, effort, and ledgerJoin.
An entry may also carry an optional ledger object recording the triage decision, e.g. {"id": "<surfaced-id>", "verdict": "rejected", "reason": "…", "ledger": {"disposition": "declined", "reason": "…", "reraiseWhen": "…"}}. disposition is filed (requires issue) | accepted | declined (both require reason) | triaged-out; optional keys are issue, reason, reraiseWhen; anything else is refused, and a degraded entry cannot carry one. A rejected entry with no ledger means {"disposition": "triaged-out", "reason": <the entry's reason>}; a validated entry with no ledger writes nothing (the decision is still pending). The ledger record's id is the surfaced id (not ledgerJoin).
Ledger-first rule. The collect step already moved filed/tracked items into ledgerStatus and suppressed settled trades. The model never re-opens those — only the surfaced list gets validated.
Write dispositions to a temp file:
DISP=$(mktemp /tmp/guardian-disp-XXXXXXXX.json)
# write the JSON array to $DISP3. Finalize
ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
python3 -B "$ROOT_DIR/lib/guardian_sweep.py" finalize --cwd . \
--bundle "$BUNDLE" --dispositions "$DISP" | jq .On success, finalize writes only guardian/report.md, compare-and-swap-replacesguardian/latest.json, and appends one line to guardian/vitals.jsonl — it does not
write ledger.md. The report shows proposed closures (the advisor commits them in
the next step). If the ledger is unreadable, finalize marks closures deferred rather
than implying none; the baseline still advances.
Refusal outcomes (surface honestly; follow each outcome's remedy):
invalid-dispositions— a surfaced id is missing, duplicated, or avalidatedentry lacks required fields. Fix the dispositions and re-run finalize with the same bundle.raced— a concurrent sweep advanced the snapshot since collect. Re-run from step 1; the prior baseline stays intact.durable-write-failed— the vitals append failed afterreport.mdlanded; the baseline does not advance — retry finalize with the same bundle.
4. Commit the ledger (advisor, at consult/triage)
ROOT_DIR="${CLAUDE_PLUGIN_ROOT}"
python3 -B "$ROOT_DIR/lib/guardian_sweep.py" commit-ledger --cwd . \
--bundle "$BUNDLE" --dispositions "$DISP" | jq .This is the only place ledger.md is written — filed-item closures, the triage
decisions from step 2's ledger objects (written as records at the decided state, which is
how a settled decision stays settled next sweep), and the per-lens report card share
this one write path. It is safe to re-run (idempotent). It
fails closed on an opaque/unreadable ledger and on a stale bundle (stale-bundle — a
newer sweep advanced the baseline since this bundle) and on a roster-read failure
(roster-read-failed, retryable) — in each case leaving on-disk bytes untouched. The
residual (an owner hand-editing the file in another window at the write instant — no lock
an external editor honors) is an accepted, documented residual (LEDGERS §3). The fenced
JSON block and the report-card region are machine-owned; owner hand-edits belong to the
surrounding prose, which the never-clobber re-splice preserves byte-for-byte.
If commit-ledger is skipped or fails, closures simply defer to the next consult — the records keep their prior state and the next sweep re-proposes the same closure, so no closure or owner content is lost. One benign caveat: because finalize already appended this sweep's vitals.jsonl line, a skipped commit can leave the vitals trend one entry ahead of the ledger's sweep roster until the next successful commit — a fail-closed parity drift (the benching floor simply counts one fewer sweep), not data loss.
Refusal outcomes (surface honestly; follow each outcome's remedy):
invalid-dispositions— same shape as finalize; fix the dispositions and re-run.raced— the sweep lock is held by another run; re-run after it settles, the prior state stays intact.stale-bundle— a newer sweep advancedlatest.jsonsince this bundle; re-run from step 1 or use a fresh bundle from the current sweep.roster-read-failed— transient roster read error; retryable.- opaque-ledger skip — ledger content is unreadable; on-disk bytes stay untouched; closures defer to the next consult — restore the ledger's readability before then.
raced-out— the never-clobber loop exhausted its bounded retries; on-disk bytes stay untouched; retry after the concurrent edit settles.
The report + storage
Artifacts live beside core.md under the band storage mode (CONVENTIONS §2):
| Path | Role | Written by |
|---|---|---|
guardian.md |
Calibration layer — thresholds, cadence, coverage records (`guardian-config` shape) | configure / rarely |
guardian/report.md |
Latest sweep report — advisor-facing plain consequences with receipts | the sweep, each finalize |
guardian/latest.json |
Drift-baseline snapshot (CAS) | the sweep, each finalize |
guardian/ledger.md |
Dispositions ledger + per-lens report card | the advisor, at consult/triage (sole writer) |
guardian/vitals.jsonl |
Append-only vitals trend history (one line per sweep) | the sweep, each finalize |
In in-repo mode these commit with the repo; in global mode they live in the project store.
The sweep writes report.md, latest.json, and vitals appends; the advisor is the sole
writer of ledger.md (closures, the per-lens report card, and dispositions) at
consult/triage. configure's one-screen view surfaces cadence,
coverage, and benched lenses (CONVENTIONS §2.1).
Ledger outcomes (report card). Adjudicated dispositions count toward each lens's
actionability mix; which outcomes count for and against is OUTCOMES_FOR / OUTCOMES_AGAINST in lib/guardian_ledger.py. A lens under the actionability bar — once it
has enough adjudicated findings across enough sweeps — is benched (see CONVENTIONS §2.1).
The lens contract
Adding a health lens is a PR that meets the lens contract with hands-on receipts from a real repo — a lens proposed from a tool's README is not a lens.
Cost + cadence
Deterministic collectors run in seconds plus one model pass. The sweep's cadence is a
project configuration item — a guardian staleness setting the project configures
(defaults: ≥10 merges or ≥14 days since the last sweep). The advisor reads that
staleness at the gardening pass; when the project is stale, the advisor runs the sweep
in that pass and triages its report in the same sitting. There is no superheroes-owned
scheduler, no cron, and no cloud routine — the sweep's artifact paths follow the
configured storage mode (in-repo with the repo; in global mode the out-of-repo project
store a cloud session cannot reach), and no mode has a hosted trigger.