rulewright 0.1.0__tar.gz

rulewright-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

rulewright-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: ci
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install ${{ matrix.python }}
+      - run: uv sync --python ${{ matrix.python }}
+      - run: uv run ruff check .
+      - run: uv run mypy rulewright
+      - run: uv run pytest
+
+  publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

rulewright-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+.venv/
+.rulewright/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+rulewright-report.md

rulewright-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `scan`: reads git history (and Claude Code session logs), finds reverts, quick human fixes of
+  agent commits and user corrections, clusters them, and proposes rules that each cite at least
+  3 distinct commits or messages. Clusters are ranked by how much their changes have in common
+  before any LLM call. Changes no file.
+- `apply`, `emit`, `init`, `stale`: accept proposed rules into `rulewright.yaml` and render
+  `AGENTS.md`, `CLAUDE.md`, `.cursorrules` and Copilot instructions between markers; find rules
+  that mention paths or commands that no longer exist. `scan --pr` opens a pull request.
+- `prove`: replay past tasks in a Docker sandbox (no network, no secrets) with and without a
+  rule and report how often the mistake recurs. Evidence, not statistical proof.
+- `guard`: propose Claude Code `permissions.allow` rules from the commands agents ran, limited
+  to a built-in list of read-only, test, lint and build commands. Reads Claude Code and Codex
+  logs; `--diff` and `--apply`.
+- LLM: a local Ollama model, or your own Groq, Anthropic or OpenAI key (any LiteLLM model name).
+  The cost is shown and a paid call needs a yes.
+
+Known limits: git history alone gives few or no rules on many repositories; Codex-authored
+commits without a trailer are not recognised; PowerShell commands are ignored by `guard`.

rulewright-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rulewright contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rulewright-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: rulewright
+Version: 0.1.0
+Summary: Mine repeated coding-agent mistakes from git history and propose evidence-backed rules.
+Project-URL: Homepage, https://github.com/AbdulRehman19-bit/rulewright
+Project-URL: Issues, https://github.com/AbdulRehman19-bit/rulewright/issues
+Author: rulewright contributors
+License: MIT License
+        
+        Copyright (c) 2026 rulewright contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents-md,ai-agents,claude-code,developer-tools,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: docker>=7
+Requires-Dist: litellm>=1.50
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=13
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: sentence-transformers>=3
+Requires-Dist: tenacity>=8
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# rulewright
+
+**Your coding agent learns from its mistakes, provably, and safely.**
+
+rulewright reads your repo's git history (and Claude Code session logs), finds the mistakes
+coding agents keep repeating, and proposes evidence-backed rules for `AGENTS.md`,
+`CLAUDE.md`, `.cursorrules` and Copilot instructions. Every rule cites at least 3 commits or
+messages. Nothing is written until you approve it.
+
+> **Status: v0.1, early.** It has been run on a handful of public repositories. It works best
+> on repos where a lot of agent-written commits get fixed by a person soon after (on litellm,
+> about 3 of 5 proposed rules were good, the rest weak). On repos with little of that it says
+> so and proposes nothing. Treat every proposal as a shortlist to review, not a list to accept.
+> `prove` and `guard` are newer still: `prove` needs Docker and shows evidence, not proof.
+
+<!-- TODO before launch: GIF of `rulewright scan` on a known public repo -->
+
+## Install
+
+```
+pipx install git+https://github.com/AbdulRehman19-bit/rulewright.git
+```
+
+Python 3.11+. Or, once published: `pipx install rulewright`.
+
+## Use
+
+```
+rulewright scan            # read the last 500 commits, print proposed rules, change nothing
+rulewright apply r-3e6f373f r-5f86d161    # accept chosen rules, write rulewright.yaml and agent files
+rulewright emit --dry-run  # preview re-rendering every agent file from rulewright.yaml
+rulewright stale           # rules that mention paths or commands that no longer exist
+rulewright prove r-3e6f373f  # replay past tasks with and without the rule (needs Docker)
+rulewright guard           # propose a permission allowlist from the commands agents ran
+rulewright guard --diff    # show the change to .claude/settings.json, write nothing
+rulewright guard --apply   # write it after you confirm
+```
+
+Mining and clustering run locally with no API key. Only the last step, writing the rule text,
+calls an LLM: a local Ollama model if one is running, otherwise your own `GROQ_API_KEY`,
+`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (or pick one with `--model`, any LiteLLM name such as
+`groq/openai/gpt-oss-120b`). The estimated cost is shown, and you are asked, before any paid call.
+
+## What a result looks like
+
+This is real output on a small demo repo with planted mistakes (not a public repo), using a local
+`qwen2.5-coder:7b`:
+
+```
+Read 45 commits (15 agent-authored); 15 signal(s) [refix] in 3 cluster(s).
+ id          proposed rule                                      scope         evidence
+ r-5f86d161  Do not skip failing pytest tests; fix them instead. tests/*.py    e0d279a, b4b4120, 4365f63 +2
+```
+
+`rulewright-report.md` lists the evidence behind each rule as commit links.
+
+**Rule quality depends on the model.** On busy real repositories a small local model (7B) wrote
+generic rules from good clusters. A second check asks the model whether each rule is specific or
+generic advice and drops the generic ones (`--no-judge` skips it), but judge every rule by its
+evidence, and for real repos use a stronger model, for example
+`rulewright scan --model groq/openai/gpt-oss-120b` with your own key (the cost is shown first).
+
+## How it stays safe
+
+rulewright writes text that agents will obey, so everything it mines is treated as hostile.
+
+- Mined text reaches the LLM only inside a delimited data block (random tag), and the reply must
+  match a fixed schema.
+- Proposed rules are scanned for URLs, curl/wget, credentials, env files, new shell commands and
+  disabling tests or permissions. Flagged rules are shown in red and never pre-selected.
+- A rule needs 3+ pieces of evidence, and each cited commit must exist in your repo.
+- Likely secrets are redacted before any API call.
+- Nothing is written without `apply` (or a pull request you review). Only the content between
+  `<!-- rulewright:start -->` and `<!-- rulewright:end -->` is ever edited.
+
+See [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+- **v0.1** `scan`, `apply`, `emit`, `stale`: this release.
+- **v0.2** `prove` (implemented, pre-release): replay past tasks in a Docker sandbox (no network,
+  no secrets) with and without a rule and report how often the mistake recurs. Results are
+  evidence, not statistical proof: a handful of tasks, nondeterministic agents, and prompts rebuilt
+  from commit messages. The built-in agent is simple; its runs are only as good as the model.
+- **v0.3** `guard` (implemented, pre-release): reads the shell commands your agents ran (Claude
+  Code and Codex logs) and proposes `permissions.allow` rules for Claude Code, but only for a
+  short built-in list of read-only, test, lint and build commands. Everything else it sees is
+  shown for you to judge, and risky commands (`rm`, `curl`, `git push`, interpreters, `docker`) are
+  never offered. It runs no LLM and executes nothing.
+
+How it works and why each choice was made: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md),
+[docs/DECISIONS.md](docs/DECISIONS.md).

rulewright-0.1.0/README.md

@@ -0,0 +1,92 @@
+# rulewright
+
+**Your coding agent learns from its mistakes, provably, and safely.**
+
+rulewright reads your repo's git history (and Claude Code session logs), finds the mistakes
+coding agents keep repeating, and proposes evidence-backed rules for `AGENTS.md`,
+`CLAUDE.md`, `.cursorrules` and Copilot instructions. Every rule cites at least 3 commits or
+messages. Nothing is written until you approve it.
+
+> **Status: v0.1, early.** It has been run on a handful of public repositories. It works best
+> on repos where a lot of agent-written commits get fixed by a person soon after (on litellm,
+> about 3 of 5 proposed rules were good, the rest weak). On repos with little of that it says
+> so and proposes nothing. Treat every proposal as a shortlist to review, not a list to accept.
+> `prove` and `guard` are newer still: `prove` needs Docker and shows evidence, not proof.
+
+<!-- TODO before launch: GIF of `rulewright scan` on a known public repo -->
+
+## Install
+
+```
+pipx install git+https://github.com/AbdulRehman19-bit/rulewright.git
+```
+
+Python 3.11+. Or, once published: `pipx install rulewright`.
+
+## Use
+
+```
+rulewright scan            # read the last 500 commits, print proposed rules, change nothing
+rulewright apply r-3e6f373f r-5f86d161    # accept chosen rules, write rulewright.yaml and agent files
+rulewright emit --dry-run  # preview re-rendering every agent file from rulewright.yaml
+rulewright stale           # rules that mention paths or commands that no longer exist
+rulewright prove r-3e6f373f  # replay past tasks with and without the rule (needs Docker)
+rulewright guard           # propose a permission allowlist from the commands agents ran
+rulewright guard --diff    # show the change to .claude/settings.json, write nothing
+rulewright guard --apply   # write it after you confirm
+```
+
+Mining and clustering run locally with no API key. Only the last step, writing the rule text,
+calls an LLM: a local Ollama model if one is running, otherwise your own `GROQ_API_KEY`,
+`ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (or pick one with `--model`, any LiteLLM name such as
+`groq/openai/gpt-oss-120b`). The estimated cost is shown, and you are asked, before any paid call.
+
+## What a result looks like
+
+This is real output on a small demo repo with planted mistakes (not a public repo), using a local
+`qwen2.5-coder:7b`:
+
+```
+Read 45 commits (15 agent-authored); 15 signal(s) [refix] in 3 cluster(s).
+ id          proposed rule                                      scope         evidence
+ r-5f86d161  Do not skip failing pytest tests; fix them instead. tests/*.py    e0d279a, b4b4120, 4365f63 +2
+```
+
+`rulewright-report.md` lists the evidence behind each rule as commit links.
+
+**Rule quality depends on the model.** On busy real repositories a small local model (7B) wrote
+generic rules from good clusters. A second check asks the model whether each rule is specific or
+generic advice and drops the generic ones (`--no-judge` skips it), but judge every rule by its
+evidence, and for real repos use a stronger model, for example
+`rulewright scan --model groq/openai/gpt-oss-120b` with your own key (the cost is shown first).
+
+## How it stays safe
+
+rulewright writes text that agents will obey, so everything it mines is treated as hostile.
+
+- Mined text reaches the LLM only inside a delimited data block (random tag), and the reply must
+  match a fixed schema.
+- Proposed rules are scanned for URLs, curl/wget, credentials, env files, new shell commands and
+  disabling tests or permissions. Flagged rules are shown in red and never pre-selected.
+- A rule needs 3+ pieces of evidence, and each cited commit must exist in your repo.
+- Likely secrets are redacted before any API call.
+- Nothing is written without `apply` (or a pull request you review). Only the content between
+  `<!-- rulewright:start -->` and `<!-- rulewright:end -->` is ever edited.
+
+See [SECURITY.md](SECURITY.md).
+
+## Roadmap
+
+- **v0.1** `scan`, `apply`, `emit`, `stale`: this release.
+- **v0.2** `prove` (implemented, pre-release): replay past tasks in a Docker sandbox (no network,
+  no secrets) with and without a rule and report how often the mistake recurs. Results are
+  evidence, not statistical proof: a handful of tasks, nondeterministic agents, and prompts rebuilt
+  from commit messages. The built-in agent is simple; its runs are only as good as the model.
+- **v0.3** `guard` (implemented, pre-release): reads the shell commands your agents ran (Claude
+  Code and Codex logs) and proposes `permissions.allow` rules for Claude Code, but only for a
+  short built-in list of read-only, test, lint and build commands. Everything else it sees is
+  shown for you to judge, and risky commands (`rm`, `curl`, `git push`, interpreters, `docker`) are
+  never offered. It runs no LLM and executes nothing.
+
+How it works and why each choice was made: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md),
+[docs/DECISIONS.md](docs/DECISIONS.md).

rulewright-0.1.0/SECURITY.md

@@ -0,0 +1,12 @@
+# Security
+
+Report vulnerabilities privately through GitHub: open
+[a security advisory](https://github.com/AbdulRehman19-bit/rulewright/security/advisories/new)
+on this repository. Please do not file a public issue for a vulnerability.
+
+## Threat model
+
+rulewright writes text that coding agents will obey, so all mined text (commit messages, diffs,
+review comments, session logs) is untrusted. Mined text is only ever passed to an LLM inside a
+delimited data block, proposed rules pass a risk scanner, each rule must cite 3+ verified
+commits, secrets are redacted before any API call, and no file is changed without `apply`.

rulewright-0.1.0/docs/ARCHITECTURE.md

@@ -0,0 +1,103 @@
+# Architecture: flow, how it works, what is used
+
+Keep this file current: update it in the same change that alters the flow, a module or a dependency.
+Why things were chosen lives in [DECISIONS.md](DECISIONS.md).
+
+## Flow
+
+```
+git history / session logs / PR comments
+   -> ingest   raw history to uniform events (no judgment)
+   -> mine     detectors find agent mistakes, score them -> Signal
+   -> cluster  embed + HDBSCAN, keep clusters of 3+ signals
+   -> propose  LLM drafts one rule per cluster, guards check it
+   -> approve  user runs `apply` (or approves a PR)
+   -> rules    rulewright.yaml (single source of truth) -> emit to AGENTS.md, CLAUDE.md, .cursorrules, copilot file
+```
+Ingest, mine and cluster run locally with no API key. Only propose calls an LLM.
+Nothing is written to an agent file without approval, and only between the rulewright markers.
+
+## Modules (package `rulewright/`)
+
+| Module | Job | State |
+|---|---|---|
+| `cli.py` | Typer app: `init`, `scan`, `apply`, `emit`, `stale`, `prove` | done |
+| `pipeline.py` | `run_scan`: ingest, detect, dedupe, score, embed, cluster, propose, stale check; writes nothing | done |
+| `report.py` | `rulewright-report.md` | done |
+| `pr.py` | `scan --pr`: branch, commit, push, `gh pr create`; GitHub commit URLs | done |
+| `config.py` | `.rulewright/config.toml` with defaults | done |
+| `ingest/git_history.py` | `git log` to `Commit` with line ranges and patch, agent attribution | done |
+| `ingest/sessions/base.py`, `claude_code.py` | `SessionSource` interface, Claude Code transcript reader | done |
+| `ingest/sessions/codex.py` | Codex rollout reader (commands only), checked against a real rollout | done |
+| `ingest/reviews.py` | PR review comments (needs token) | placeholder |
+| `mine/signals.py` | `Signal` model | done |
+| `mine/detectors.py` | revert, re-fix, correction detectors | done; review detector todo |
+| `mine/score.py` | recency weighting and threshold | done |
+| `cluster/embed.py` | `Embedder` interface, sentence-transformers embedder, SQLite embedding cache | done |
+| `cluster/group.py` | HDBSCAN grouping, `Cluster` model, `coherence` score, cold-start message | done |
+| `propose/redact.py` | secret redaction before any API call | done |
+| `propose/guards.py` | risk scanner, scope cleaning, evidence verification | done |
+| `propose/llm.py` | model choice (Ollama, else user key), LiteLLM client, cost estimate | done |
+| `propose/writer.py` | prompt with delimited data block, schema parsing, `propose_rules` | done |
+| `rules/model.py` | `Rule`, `Evidence` | done |
+| `rules/source.py` | rulewright.yaml load/save, pending-proposals store | done |
+| `rules/emit/` | marker-based block replacement, one writer per target (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md) | done |
+| `rules/stale.py` | dead paths, dead commands, dead scopes, silent rules | done |
+| `prove/tasks.py` | rebuild past tasks from a rule's evidence (parent tree, prompt, known-bad lines) | done |
+| `prove/sandbox.py` | `Sandbox` interface, `DockerSandbox` (no network, no env, caps dropped, limits) | done |
+| `prove/agent.py` | `AgentRunner` interface, `BuiltinAgent` JSON-action loop | done |
+| `prove/judge.py` | workspace snapshots, deterministic recurrence check | done |
+| `prove/runner.py` | `prove_rule`: both arms, trials, cost ceiling, LLM-judge fallback, report | done |
+| `guard/profile.py` | split commands, classify against a curated safe list, count uses, build the profile | done |
+| `guard/emit.py` | add `Bash(<prefix>:*)` rules to `.claude/settings.json` (merge, diff, atomic write) | done |
+| `store.py` | SQLite cache in `.rulewright/` (embeddings table) | embeddings done; signals and rule history later |
+
+## How the finished pieces work
+
+- **`guard`** (no LLM, nothing executed): reads the shell commands agents ran for this repo (Claude Code `Bash` tool calls with their results; Codex `shell` calls whose session `cwd` is the repo). Each command is split on `&&`, `||`, `;` and `|`; commands with `$(...)`, backticks, redirects to real files, here-documents or `FOO=bar cmd` are skipped whole (`2>&1` and `>/dev/null` are ignored). Each part is matched against our own curated list of safe prefixes (`git status`, `uv run pytest`, `cargo test`, ...); the longest match becomes the pattern, so the rule is always one of our prefixes and never text from the log. Tiers: **safe** (on the list), **review** (run often, not on the list; written only with `--include-review`), **never** (interpreters, wrappers like `timeout`, `rm`, `curl`, `git push`, `docker`, paths; reported, never offered). A command the person refused is left out. A pattern needs 3 uses (`--min-uses`). The output is `Bash(<prefix>:*)` in `permissions.allow` of `.claude/settings.json` (`--local` for settings.local.json), merged into the existing file, other keys untouched, written atomically, and only after `--apply` and a yes (or `--yes`). `--diff` prints the change and writes nothing. A settings file that is not valid JSON is refused. PowerShell commands (Claude's `PowerShell` tool, Codex `shell_command`) are counted and ignored because their rule syntax differs.
+
+- **Commit reading**: one `git log -p -U0 --numstat --no-renames` call (lockfiles, minified bundles, snapshots, SVGs and source maps are excluded at the git level); records and header fields split by control characters. Each commit keeps per-file counts, changed line ranges, the text of added and removed lines (capped at 1000 per file) and a truncated patch. A commit is agent-authored if its body has a Co-Authored-By trailer naming a coding agent (Claude, Codex, Copilot, Cursor, Devin, Aider, OpenHands, Jules, Gemini, Sweep), or its author is a `[bot]` whose name contains one of those, or `noreply@anthropic.com`. Release and dependency bots (dependabot, github-actions, huppy-bot) are not agents.
+- **Revert detector**: an agent commit followed within 7 days by a commit that names it in "This reverts commit <sha>" (confidence 1.0), or that removes at least 50% of the significant lines the agent added (matched by line content, each added line matching at most once) in the same files (0.6). The signal's excerpt is the human's change (`- removed` / `+ added`).
+- **Re-fix detector**: a human commit within 48 hours that removes lines the agent commit added, where the removed line numbers also overlap the agent's added range in the same file (0.8). Explicit reverts are skipped; one event is one signal (revert and re-fix signals for the same commit pair are deduplicated, highest confidence kept).
+- **Session reader**: reads `~/.claude/projects/<slug>/*.jsonl`, keeps only text blocks of user/assistant records, skips sidechains, meta records and malformed lines.
+- **Correction detector** (0.5): a user message that follows an assistant turn, is at most 400 characters, is not harness-injected text, and opens with a rejection phrase ("no", "don't", "stop", "instead" ...). Its signal has no commit SHA; the evidence is the session message.
+- **Scoring**: detectors emit confidence in `score`; `score_signals` multiplies by a recency weight (half-life 180 days) and drops anything below 0.2. Apply once per run.
+- **Embedding**: each signal becomes a short summary (`kind: text (files: ...)`), embedded with `all-MiniLM-L6-v2` (offline after the first model download). Vectors are cached in SQLite keyed by model and SHA-256 of the text, so a rescan only embeds new signals.
+- **Clustering**: scikit-learn HDBSCAN, min cluster size 3, first in its strict mode; only if that finds nothing is it retried allowing a single cluster (the lone repeated mistake case). Noise and groups under 3 are dropped. The embedded summary starts with the human's change excerpt, then the commit subjects. A cluster has a deterministic id (hash of its signal ids), a centroid and the text of the signal nearest the centroid as its summary.
+- **Cold start**: fewer than 3 clusters gives a plain message suggesting `--commits 2000` or session logs, instead of inventing weak rules.
+- **Propose**: per cluster, `build_prompt` sends the fixed instructions as the system message and the top 12 signals as JSON lines inside `<mined-data-RANDOM>` tags (the text can neither guess nor close the tag). Everything is redacted first (key patterns, secret-named assignments, high-entropy tokens; git SHAs are kept). The prompt demands a rule specific to the repository and lets the model decline with an empty rule (dropped as "no specific repeated mistake"). The reply must parse into `{rule, scope, cited_signals}`; anything else drops the cluster.
+- **Guards**: a rule keeps only cited signals that belong to its cluster and whose evidence is real (the commit exists in the repo, or it is a session message). Evidence is counted per distinct commit (several fixes of one commit are one item); fewer than 3 means the rule is dropped. Rule text is scanned for URLs, network commands, credentials, env files, new shell commands, disabling tests or permissions, injection phrases and length over 30 words; prohibitions such as "never skip tests" pass. Flagged rules are kept with `risk_flags` set so the UI can show them red and unselected. Scope must be repo-relative globs.
+- **Model and cost**: a local Ollama model if one is running, else `ANTHROPIC_API_KEY`, else `OPENAI_API_KEY`, else none. `estimate_cost` approximates tokens (chars / 4) and prices them through LiteLLM; local models are free, unknown models give no price. The scan command (phase 6) must show it and ask before a paid call.
+- **Source of truth**: `rulewright.yaml` (version, targets, rules with id, text, scope, status, evidence refs). Evidence is stored as commit SHAs, or signal ids for session messages. `scan` (phase 6) will leave proposals in `.rulewright/pending.json`; nothing reaches the yaml until `apply`.
+- **Emit**: only accepted rules are rendered. Content goes between `<!-- rulewright:start -->` and `<!-- rulewright:end -->`: a missing file is created, a file without markers gets the block appended after a blank line, a file with markers has only that span replaced (line endings kept). Broken markers (missing, duplicated, reversed) abort with an error before any file is written. Rule text is flattened to one line and marker strings are stripped from it.
+- **Commands**: `init` writes an empty rulewright.yaml. `apply [ids] | --all-safe` moves pending rules into the yaml as accepted and emits the targets; risk-flagged rules need `--allow-risky`. `emit [--dry-run]` re-renders every target (the dry run prints a diff and writes nothing). `stale [--mark]` lists findings and can set those rules to `stale`, which the next `emit` leaves out.
+- **Stale check**: for accepted rules, a path-like token that is not a tracked file or directory, a backticked `make X` / `npm run X` whose target or script does not exist, a scope glob matching no tracked file, and (given signals) no signal in the last 90 days that touches the rule's scope or shares two content words with it.
+- **Scan** (`rulewright scan`): reads N commits (default 500) and Claude Code session logs, runs the detectors, keeps one signal per (agent commit, later commit) pair, scores, embeds, clusters. Fewer than 3 clusters means the cold-start message and no LLM call. Otherwise up to 10 clusters not already covered by a rule in rulewright.yaml go to the LLM, chosen by `select_clusters`: clusters whose changes share almost no identifiers (coherence under 0.10) are skipped with a note, and the rest are ranked by coherence, then distinct commits; the cost estimate is shown first and a paid call needs a yes (`--yes` skips the question; local models are free and never ask). It prints a Rich table (flagged rules red), writes `rulewright-report.md`, and stores the proposals in `.rulewright/pending.json` (replacing the previous list). It changes no agent file and not rulewright.yaml.
+- **`--pr`**: puts the guard-approved rules (no risk flags) on a branch `rulewright/rules-<timestamp>` with rulewright.yaml and the target files, pushes it and opens a pull request with `gh`. The PR is the approval step. It refuses if the files it would edit have uncommitted changes or broken markers, and returns to the original branch. A missing remote or `gh` is reported as a note.
+- **Report**: counts, the cold-start message, each rule with scope, risk flags and evidence as commit links (GitHub repos), dropped clusters and stale rules. It contains SHAs and signal kinds, never mined text.
+- **Prove** (`rulewright prove <rule-id>`): re-mines the history to find the rule's evidence commits and, for each, the lines the human fix removed (the mistake). A task is the agent commit's parent tree (`git archive`, no history, so the fix is not visible), a prompt taken from the agent commit's message (attribution lines removed) and those bad lines. Up to 10 tasks. For each task and trial it runs two arms on fresh copies: without the rule and with the rule in the agent's system prompt. After a cost estimate (free for local models; a paid run asks first; `--max-cost` stops the run at the ceiling) each run goes: temp copy, Docker container (no network, no environment variables, all capabilities dropped, no-new-privileges, 1 GB memory, 1 CPU, 256 processes, commands killed after 60 s, image `python:3.12-slim`), built-in agent loop, then the judge. The agent loop runs on the host so the API key never enters the container; the container only executes the agent's file and shell actions. File reads and writes go through the container, never host-side, and host snapshots skip symlinks. The judge is deterministic when the evidence shows the mistake (the agent wrote one of the removed lines), otherwise an LLM judge decides. The report shows, per arm, recurrences out of judged runs, runs that changed files (so "did nothing" is not mistaken for "avoided the mistake"), runs that failed (excluded) and cost, and is saved to `.rulewright/prove/<rule-id>.json`.
+- **Tests**: `tests/fixtures/build_repos.py` builds throwaway repos with planted patterns and negative cases; transcripts are generated in tmp dirs; tests assert detectors find exactly the planted signals.
+
+## What is used
+
+Python 3.11+, Typer + Rich (CLI), Pydantic v2 (models), PyYAML (rulewright.yaml), git via subprocess, hatchling (build), uv (dev), pytest, ruff, mypy (strict), GitHub Actions on Python 3.11-3.13.
+CI also publishes to PyPI on `v*` tags (trusted publishing). Also now: docker (docker-py), sentence-transformers (torch), scikit-learn HDBSCAN, numpy, SQLite. LiteLLM (lazy import).  Planned: SQLite, PyYAML; v0.2 Docker (docker-py).
+
+## Phases
+
+Spec timeline: v0.1 ends week 3 (phases 0-6), v0.2 ends week 7 (phase 7), v0.3 after that (phase 8).
+Week 1 = phases 0-1, week 2 = phase 2 plus embeddings/clustering (phase 3), week 3 = phases 4-6.
+
+| Phase | Scope | Status |
+|---|---|---|
+| 0 Scaffold | repo layout, pyproject, CI, SECURITY.md, stub CLI | done |
+| 1 Ingest + revert | git ingest, Signal, revert detector, fixture script | done |
+| 2 Detect + score | re-fix detector, Claude Code session reader + correction detector, scoring and threshold done; optional review detector (GitHub token) todo | mostly done |
+| 3 Cluster | local embeddings cached in SQLite, HDBSCAN, 3+ signal rule, cold-start message | done |
+| 4 Propose + guard | LiteLLM writer with delimited data block, schema-parsed output, risk scanner, secret redaction, SHA verification, cost estimate | done (real LLM path not yet run) |
+| 5 Rules + emit | rulewright.yaml, marker-based emitters with golden tests, stale check, `init`, `apply`, `emit`, `stale` | done |
+| 6 Ship v0.1 | `scan`, Rich table, rulewright-report.md, `--pr`, injection tests, README; real-repo check on litellm, tldraw (done, found and fixed 4 bugs) | code done; launch gate partly done |
+
+Launch gate for v0.1 (partly done: real scans on litellm with Groq reviewed by hand, four more repos surveyed; see D75, D77): run `scan` on 3 public repos that have agent co-authored commits and read the output by hand; record the GIF; renamed from `rulesmith`, which is taken on PyPI (D79, D80); rename the GitHub repository, then configure the PyPI trusted publisher. Done: LICENSE, package metadata, clean-install check, security contact via GitHub advisories (enable it in repo settings).
+| 7 v0.2 prove | rebuild tasks, cost estimate/`--max-cost`, Docker sandbox, AgentRunner, judge, before/after report | code done and tested against real containers; real-model replay in progress (see D70) |
+| 8 v0.3 guard | permission profiler, allowlist emitter, `guard --diff`/`--apply`, Codex reader | code done and tested; run on this machine's real logs (see D78) |