@syv-ai/rulecast 0.1.1 → 0.3.0

package/README.md

@@ -92,6 +92,7 @@ A refusal only ever rests on the text the agent is writing, never on a reconstru
 | `rulecast init` | Interactive setup |
 | `rulecast install` / `uninstall` | Add or remove the agent hooks |
 | `rulecast run` | Check staged files, changed files, or everything |
+| `rulecast test` | Run each rule's good/bad examples; `--against` says how much it would flag |
 | `rulecast validate` | Check the config and print diagnostics |
 | `rulecast doctor` | Compile, check the environment, dry-run every rule |
 | `rulecast autoupdate` | Move pinned rule repos to their latest tag |
@@ -102,11 +103,57 @@ A refusal only ever rests on the text the agent is writing, never on a reconstru
 
 `rulecast run` is also how you use rulecast in CI. `--from-ref main` checks only what a branch changed, which matters most for `llm` rules — they judge changed files only.
 
+## Adopting a rule on a codebase that already breaks it
+
+`rulecast run --all-files --summary` tells you how much you already owe:
+
+```text
+backlog: 57 violations in 31 files
+
+  rule                            violations  files
+  python/routes-never-call-crud           57     31
+
+  worst files                     violations
+  app/api/routes/orders.py                12
+  app/api/routes/users.py                  9
+```
+
+Watch the count, not the rate. Here is one real codebase on one rule, on `main`:
+
+| date | violating / total |
+|---|---|
+| 2026-01-15 | 61 / 80 |
+| 2026-06-01 | 58 / 143 |
+| 2026-09-25 | 57 / 194 |
+
+The rate fell from 76% to 29% and the count did not move. New code complied; the old violations were
+never fixed, only diluted. A team watching the percentage would have believed it was winning.
+
+Per-edit enforcement does not touch that stock — it only stops it growing. Fix it a file at a time:
+edits to files that already followed the rule broke it 2% of the time, against 37% in files that
+mostly did not, so a file you clean tends to stay clean. (One rule across 19 files: suggestive, not
+proven.)
+
 If something is configured but quiet, `rulecast doctor` says why: it compiles the config, reports whether each rule's linter, parser, script or API key is actually there, says where the hooks and caches live, and runs every rule against one file it matches.
 
 ## Agents
 
-rulecast ships docs written for coding agents, not for people:
+rulecast ships docs written for coding agents, not for people. Paste this to yours and it will set
+rulecast up itself:
+
+```text
+Set up rulecast in this project. Read
+https://raw.githubusercontent.com/syv-ai/rulecast/v0.3.0/agents/SETUP.md
+and follow it. Show me every file it creates or changes before I commit anything.
+```
+
+If your agent cannot fetch a URL, this is the whole of it: run
+`npx @syv-ai/rulecast init --yes --agent <your agent, e.g. claude-code>`, then show me
+`.rulecast-config.yaml` and the other files it listed. Never edit hook settings by hand —
+`rulecast install` and `rulecast uninstall` own them.
+
+Once it is set up, ask the same agent to draft rules for your own conventions; `init` prints the
+prompt to paste.
 
 - [`agents/SETUP.md`](https://github.com/syv-ai/rulecast/blob/main/agents/SETUP.md) — give this to your agent and it will set rulecast up itself.
 - [`agents/DRAFT-RULES.md`](https://github.com/syv-ai/rulecast/blob/main/agents/DRAFT-RULES.md) — it reads your `AGENTS.md`, proposes one rule per convention that code can visibly break, shows you what each would flag today, and asks you to keep, edit or drop it.
@@ -138,7 +185,7 @@ The budget is what shapes the design: one detector run per kind per event, kinds
 
 0.1. Everything above works and is tested. The config format may still change before 1.0 — `minimum_rulecast_version` exists so a rule can say what it needs.
 
-Next: adapters for Codex, Cursor and OpenCode; Biome; rule tests (good and bad examples run by `rulecast test`); an Azure OpenAI provider.
+Next: adapters for Codex, Cursor and OpenCode; Biome; an Azure OpenAI provider.
 
 ## License