A repo that audits, fixes, and hardens itself.

One healer, one axis

Each healer ships as one skill — skills/<axis>/SKILL.md — and is a self-contained audit spec: the surface it owns, the checks it runs, its fix policy, and the .heal/backlog.md heading it converges findings to. /heal:security knows nothing about bundle budgets; /heal:perf never touches auth. Narrow scope is what keeps each audit deep and each verdict trustworthy.

An orchestrator, not a monolith

/heal:sweep resolves the enabled axes at runtime (never a hardcoded list), fans the independent read-only ones out as parallel agents, and fuses their reports into one dashboard. Its real value is cross-axis correlation: an IDOR flagged by security, an ownership-scoping gap flagged by arch, and a missing abuse-case test flagged by tests are one root cause seen through three lenses — and get ranked as one high-leverage cluster.

Idempotent by contract

Every healer is written to run on a schedule: a healthy repo yields a clean report and zero edits. Findings that can't be fixed now are persisted as checklist items so the next run builds on the last instead of re-reporting the same thing forever.

What it can achieve

• A single health number + backlog count a loop or schedule can watch trend over time.
• Findings as data — fingerprinted findings.json sidecars enable new / fixed / persisting diffs between runs.
• Fixes as reviewable PRs — mechanical fixes land as focused branches off the project's integration branch, never silent edits to a protected one.
• Fewer repeat findings — recurring issues get promoted into durable guardrails (rules, hooks, scripts, tests).
• A shareable HTML dashboard per run — zero token cost, pure render of on-disk data.

Durable state lives in .heal/backlog.md

Run dirs are ephemeral; the backlog is not. Each axis owns a heading (## Security health, ## Quality debt, ## Healer drift, …) and converges to it idempotently. /heal:fix ticks items [x] with a dated resolution note and moves them to .heal/archive/backlog.md in the same commit as the fix — the archive holds the checked audit trail, the active file only open work. .heal/backlog.md is convergence-only; a human-shipped tradeoff gets its own .heal/tradeoffs/<slug>.md shard (one file per entry, so two PRs never collide on a shared insertion anchor), ticked [x] in place.

Trend as data, not memory

heal-run.mjs trend joins a run's findings against the previous run by fingerprint id and prints new / fixed / persisting / accepted counts plus the burden delta. Accepted risks live in .heal/baseline.json — the single source of acceptance truth — so they never re-count as new. No LLM recollection involved — it's a deterministic join.

• The axis set is resolved, never hardcoded. /heal:sweep reads the axes enabled in .claude/heal.json, so turning one on adds it to every future sweep — and the gate immediately enforces its structure. Updating the plugin updates every project at once; the config and the findings stay yours.
• Coverage holes become drafts. When /heal:self finds an invariant no healer checks, it drafts a ready-to-apply check — evidence, owning healer, exact placement, copy-pasteable text — but a human applies it. This prevents command bloat, overfitting, and structural corruption in the very files that drive the loop.

• Recurrence escalates. /heal:prevent proposes a guardrail on a finding's first appearance and escalates emphasis when it recurs — and flags guardrails that exist but aren't holding, so they get promoted to something stronger.
• Guardrails graduate into code. A check that keeps being proposed gets written: the trajectory is always LLM finding → persistent backlog → durable script / rule / test, at which point the expensive reasoning is spent once and re-verified for free.