pushback 0.1.0__tar.gz

pushback-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intikhab Azam
+
+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.

pushback-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: pushback
+Version: 0.1.0
+Summary: How often do you correct your coding agent, and at what kind of work? Measured from your own Claude Code transcripts.
+Author: Intikhab Azam
+License: MIT
+Project-URL: Homepage, https://github.com/intikhab49/pushback
+Project-URL: Repository, https://github.com/intikhab49/pushback
+Project-URL: Issues, https://github.com/intikhab49/pushback/issues
+Keywords: claude-code,coding-agents,ai-agents,llm,claude,claude-md,dpo,preference-data,llm-evaluation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# pushback
+
+How often do you correct your coding agent, and on what kind of work?
+
+`pushback` reads your Claude Code transcripts, labels every message you sent
+with Claude, and tells you what share of your messages were corrections,
+broken down by the kind of work in progress (code, writing, media, research,
+ops, meta). A hand-check step tells you how far to trust the labels.
+
+On the author's own 1,633 messages:
+
+| task | messages | corrections | rate | 95% CI |
+|---|---:|---:|---:|---|
+| media | 114 | 49 | 43.0% | 34.3%–52.2% |
+| writing | 429 | 106 | 24.7% | 20.9%–29.0% |
+| research | 188 | 13 | 6.9% | 4.1%–11.5% |
+| code | 340 | 20 | 5.9% | 3.8%–8.9% |
+| meta | 297 | 14 | 4.7% | 2.8%–7.8% |
+| ops | 265 | 12 | 4.5% | 2.6%–7.7% |
+
+Against 91 hand-checked messages the labels had precision 0.97 and recall 0.80.
+That's one person's logs. Run it on yours.
+
+These rates describe a workflow, not a model. The author's code work runs
+through skills, reference files, memory and a plan before the agent writes
+anything, and CI catches mistakes before a human has to. Writing got none of
+that. A low rate means the process around the agent is doing its job.
+
+## Run it
+
+```
+pip install pushback          # or, from a clone: pip install -e .
+pushback extract            # reads ~/.claude/projects, writes ./pushback-data/
+pushback label              # sends your messages to Claude, resumable
+pushback audit              # hand-check 40 messages
+pushback report --markdown  # the table, with the audit folded in
+pushback rules              # draft CLAUDE.md rules from your recurring corrections
+pushback export             # your corrections as prompt/chosen/rejected pairs
+```
+
+`label` uses the Anthropic SDK, so it picks up `ANTHROPIC_API_KEY` or an
+`ant auth login` profile. It defaults to `claude-opus-5` at low effort. Change
+it with `--model`. To send through a gateway, set `ANTHROPIC_BASE_URL`.
+
+## Turn recurring corrections into rules
+
+```
+pushback rules                                  # drafts rules into pushback-data/rules.md
+pushback rules --existing CLAUDE.md notes/*.md  # also check against the rules you already have
+pushback rules --prompt-file                    # no API key? writes the request to a file instead
+pushback rules --from-response reply.json       # ...and reads Claude's answer back
+```
+
+The model groups corrections that share a cause and drafts one CLAUDE.md
+instruction per group. Support is counted from the correction ids it cites,
+not from its own numbers, and a rule needs at least 3 real corrections.
+
+When you pass your existing rule files, the output splits in two:
+
+- **Rules you already have that keep getting broken.** These are the useful
+  ones. A rule that exists and still gets corrected isn't working: it's too
+  vague, or the agent doesn't read it at the right moment.
+- **New rules to consider.** Recurring corrections with no rule behind them.
+
+No API key: `--prompt-file` writes the whole request to `rules-prompt.md`.
+Ask Claude Code to answer it, save the JSON reply, then run `--from-response`.
+
+## Export your corrections as preference pairs
+
+```
+pushback export                                        # all pairs -> pushback-data/dpo.jsonl
+pushback export --ctype writing_content tone_style     # the cleanest pairs
+pushback export --minimal                              # only prompt/chosen/rejected (TRL DPO columns)
+```
+
+Each correction you made becomes one row:
+
+- `prompt`: your message the agent was answering
+- `rejected`: the agent turn you corrected
+- `chosen`: the agent's reply to your correction, kept only if your next message wasn't another correction
+- `feedback`: the correction itself, for critique-and-revise formats
+
+On the author's logs, 214 corrections gave 124 pairs. The biggest loss:
+70 corrections (a third) had their fix corrected too, so there was no
+accepted answer to pair with.
+
+What to know before you train on it:
+
+- "You didn't correct it again" is weak evidence that the fix was good.
+- The fix was written after seeing your feedback. For corrections of a wrong
+  assumption ("I already sent that"), `chosen` answers the correction rather
+  than the prompt. Those make poor DPO pairs, so filter with `--ctype`.
+- Only agent text is exported. File edits and commands are tool calls, so a
+  code correction's pair may hold the explanation without the diff. Use
+  `--max-tools` to drop tool-heavy turns.
+- Secrets are scrubbed on a best-effort basis (API key shapes, tokens,
+  `NAME_KEY=value`). Read the file before you use it.
+- Your transcripts probably contain other people's information. Keep the
+  export local unless every conversation in it is yours to share.
+- If the agent is Claude, Anthropic's terms restrict using its outputs to
+  build competing models. Treat this as a personal dataset or eval set.
+
+## What counts as a correction
+
+A message where you reject, fix or redirect something the agent just did,
+said, wrote or proposed. New tasks, answers to its questions, picking between
+its options, approvals and pasted logs don't count. The full rubric is in
+`src/pushback/prompt.py`. If you change it, run `audit` again.
+
+Rejected tool calls and interrupts carry no text, so they're counted
+separately and bucketed by the action you stopped (a code edit, a shell
+command, and so on).
+
+## Privacy
+
+- `extract` and `report` never leave your machine. `report` prints counts only.
+- `label` sends each message, plus the end of the agent reply before it, to the
+  model provider. If your logs contain client work, check that provider's data
+  policy first. `label` asks before it sends anything.
+- `pushback-data/` holds your raw messages. It's in `.gitignore`. Keep it there.
+
+## Your history is shorter than you think
+
+Claude Code deletes transcripts older than 30 days by default. To keep more,
+set `cleanupPeriodDays` in `~/.claude/settings.json`, for example
+`"cleanupPeriodDays": 365`. It only affects transcripts that still exist.
+
+## How the numbers are computed
+
+- Rates per task come with Wilson 95% intervals.
+- `audit` samples half from messages the model flagged and half from the rest.
+  The report estimates the true count as
+  `flagged × precision + unflagged × miss rate`, with a range built from both
+  strata's intervals.
+- A batch that fails stays unlabelled and is retried on the next run. It's
+  never counted as "not a correction".
+
+## Limits
+
+- Claude Code transcripts only, for now.
+- Task type is judged from the last agent reply and your message, not the whole session.
+- The rubric was tuned on one person's logs.
+
+MIT licensed.

pushback-0.1.0/README.md

@@ -0,0 +1,144 @@
+# pushback
+
+How often do you correct your coding agent, and on what kind of work?
+
+`pushback` reads your Claude Code transcripts, labels every message you sent
+with Claude, and tells you what share of your messages were corrections,
+broken down by the kind of work in progress (code, writing, media, research,
+ops, meta). A hand-check step tells you how far to trust the labels.
+
+On the author's own 1,633 messages:
+
+| task | messages | corrections | rate | 95% CI |
+|---|---:|---:|---:|---|
+| media | 114 | 49 | 43.0% | 34.3%–52.2% |
+| writing | 429 | 106 | 24.7% | 20.9%–29.0% |
+| research | 188 | 13 | 6.9% | 4.1%–11.5% |
+| code | 340 | 20 | 5.9% | 3.8%–8.9% |
+| meta | 297 | 14 | 4.7% | 2.8%–7.8% |
+| ops | 265 | 12 | 4.5% | 2.6%–7.7% |
+
+Against 91 hand-checked messages the labels had precision 0.97 and recall 0.80.
+That's one person's logs. Run it on yours.
+
+These rates describe a workflow, not a model. The author's code work runs
+through skills, reference files, memory and a plan before the agent writes
+anything, and CI catches mistakes before a human has to. Writing got none of
+that. A low rate means the process around the agent is doing its job.
+
+## Run it
+
+```
+pip install pushback          # or, from a clone: pip install -e .
+pushback extract            # reads ~/.claude/projects, writes ./pushback-data/
+pushback label              # sends your messages to Claude, resumable
+pushback audit              # hand-check 40 messages
+pushback report --markdown  # the table, with the audit folded in
+pushback rules              # draft CLAUDE.md rules from your recurring corrections
+pushback export             # your corrections as prompt/chosen/rejected pairs
+```
+
+`label` uses the Anthropic SDK, so it picks up `ANTHROPIC_API_KEY` or an
+`ant auth login` profile. It defaults to `claude-opus-5` at low effort. Change
+it with `--model`. To send through a gateway, set `ANTHROPIC_BASE_URL`.
+
+## Turn recurring corrections into rules
+
+```
+pushback rules                                  # drafts rules into pushback-data/rules.md
+pushback rules --existing CLAUDE.md notes/*.md  # also check against the rules you already have
+pushback rules --prompt-file                    # no API key? writes the request to a file instead
+pushback rules --from-response reply.json       # ...and reads Claude's answer back
+```
+
+The model groups corrections that share a cause and drafts one CLAUDE.md
+instruction per group. Support is counted from the correction ids it cites,
+not from its own numbers, and a rule needs at least 3 real corrections.
+
+When you pass your existing rule files, the output splits in two:
+
+- **Rules you already have that keep getting broken.** These are the useful
+  ones. A rule that exists and still gets corrected isn't working: it's too
+  vague, or the agent doesn't read it at the right moment.
+- **New rules to consider.** Recurring corrections with no rule behind them.
+
+No API key: `--prompt-file` writes the whole request to `rules-prompt.md`.
+Ask Claude Code to answer it, save the JSON reply, then run `--from-response`.
+
+## Export your corrections as preference pairs
+
+```
+pushback export                                        # all pairs -> pushback-data/dpo.jsonl
+pushback export --ctype writing_content tone_style     # the cleanest pairs
+pushback export --minimal                              # only prompt/chosen/rejected (TRL DPO columns)
+```
+
+Each correction you made becomes one row:
+
+- `prompt`: your message the agent was answering
+- `rejected`: the agent turn you corrected
+- `chosen`: the agent's reply to your correction, kept only if your next message wasn't another correction
+- `feedback`: the correction itself, for critique-and-revise formats
+
+On the author's logs, 214 corrections gave 124 pairs. The biggest loss:
+70 corrections (a third) had their fix corrected too, so there was no
+accepted answer to pair with.
+
+What to know before you train on it:
+
+- "You didn't correct it again" is weak evidence that the fix was good.
+- The fix was written after seeing your feedback. For corrections of a wrong
+  assumption ("I already sent that"), `chosen` answers the correction rather
+  than the prompt. Those make poor DPO pairs, so filter with `--ctype`.
+- Only agent text is exported. File edits and commands are tool calls, so a
+  code correction's pair may hold the explanation without the diff. Use
+  `--max-tools` to drop tool-heavy turns.
+- Secrets are scrubbed on a best-effort basis (API key shapes, tokens,
+  `NAME_KEY=value`). Read the file before you use it.
+- Your transcripts probably contain other people's information. Keep the
+  export local unless every conversation in it is yours to share.
+- If the agent is Claude, Anthropic's terms restrict using its outputs to
+  build competing models. Treat this as a personal dataset or eval set.
+
+## What counts as a correction
+
+A message where you reject, fix or redirect something the agent just did,
+said, wrote or proposed. New tasks, answers to its questions, picking between
+its options, approvals and pasted logs don't count. The full rubric is in
+`src/pushback/prompt.py`. If you change it, run `audit` again.
+
+Rejected tool calls and interrupts carry no text, so they're counted
+separately and bucketed by the action you stopped (a code edit, a shell
+command, and so on).
+
+## Privacy
+
+- `extract` and `report` never leave your machine. `report` prints counts only.
+- `label` sends each message, plus the end of the agent reply before it, to the
+  model provider. If your logs contain client work, check that provider's data
+  policy first. `label` asks before it sends anything.
+- `pushback-data/` holds your raw messages. It's in `.gitignore`. Keep it there.
+
+## Your history is shorter than you think
+
+Claude Code deletes transcripts older than 30 days by default. To keep more,
+set `cleanupPeriodDays` in `~/.claude/settings.json`, for example
+`"cleanupPeriodDays": 365`. It only affects transcripts that still exist.
+
+## How the numbers are computed
+
+- Rates per task come with Wilson 95% intervals.
+- `audit` samples half from messages the model flagged and half from the rest.
+  The report estimates the true count as
+  `flagged × precision + unflagged × miss rate`, with a range built from both
+  strata's intervals.
+- A batch that fails stays unlabelled and is retried on the next run. It's
+  never counted as "not a correction".
+
+## Limits
+
+- Claude Code transcripts only, for now.
+- Task type is judged from the last agent reply and your message, not the whole session.
+- The rubric was tuned on one person's logs.
+
+MIT licensed.

pushback-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pushback"
+version = "0.1.0"
+description = "How often do you correct your coding agent, and at what kind of work? Measured from your own Claude Code transcripts."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = ["anthropic>=1.0"]
+authors = [{name = "Intikhab Azam"}]
+keywords = ["claude-code", "coding-agents", "ai-agents", "llm", "claude", "claude-md", "dpo", "preference-data", "llm-evaluation"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/intikhab49/pushback"
+Repository = "https://github.com/intikhab49/pushback"
+Issues = "https://github.com/intikhab49/pushback/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.scripts]
+pushback = "pushback.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

pushback-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pushback-0.1.0/src/pushback/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pushback-0.1.0/src/pushback/audit.py

@@ -0,0 +1,63 @@
+"""Hand-check a stratified sample so the report can say how far to trust the labels.
+
+Half the sample comes from messages the model called corrections, half from
+the rest. Your answers never leave your machine.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+
+PROMPT = "Is this a correction of the agent? [y]es / [n]o / [s]kip / [q]uit: "
+
+
+def load_audit(path: str) -> dict[str, dict]:
+    audit: dict[str, dict] = {}
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                if line.strip():
+                    d = json.loads(line)
+                    audit[d["id"]] = d
+    return audit
+
+
+def sample(messages: dict[str, dict], labels: dict[str, dict], done: set[str], n: int, seed: int) -> list[tuple[str, str]]:
+    rng = random.Random(seed)
+    pos = sorted(i for i, d in labels.items() if d["correction"] and i not in done and i in messages)
+    neg = sorted(i for i, d in labels.items() if not d["correction"] and i not in done and i in messages)
+    rng.shuffle(pos)
+    rng.shuffle(neg)
+    half = n // 2
+    picked = [(i, "flagged") for i in pos[:half]] + [(i, "unflagged") for i in neg[: n - half]]
+    rng.shuffle(picked)  # don't let the order hint at the model's answer
+    return picked
+
+
+def run(messages, labels, audit_path, n=40, seed=0, ask=input, show=print) -> int:
+    done = load_audit(audit_path)
+    todo = sample(messages, labels, set(done), n, seed)
+    if not todo:
+        show("nothing left to audit")
+        return 0
+    answered = 0
+    with open(audit_path, "a", encoding="utf-8") as out:
+        for k, (i, stratum) in enumerate(todo, 1):
+            m = messages[i]
+            show(f"\n--- {k}/{len(todo)} ---")
+            show(f"AGENT: ...{m['prev_assistant'][-300:]}")
+            show(f"YOU:   {m['user']}")
+            while True:
+                a = ask(PROMPT).strip().lower()[:1]
+                if a in ("y", "n", "s", "q"):
+                    break
+            if a == "q":
+                break
+            if a == "s":
+                continue
+            out.write(json.dumps({"id": i, "stratum": stratum, "human": a == "y"}) + "\n")
+            out.flush()
+            answered += 1
+    return answered

pushback-0.1.0/src/pushback/cli.py

@@ -0,0 +1,231 @@
+"""pushback: how often do you correct your coding agent, and at what kind of work?"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from . import audit as audit_mod
+from . import export as export_mod
+from . import extract as extract_mod
+from . import label as label_mod
+from . import report as report_mod
+from . import rules as rules_mod
+
+DATA = "pushback-data"
+
+
+def _paths(data_dir: str) -> dict[str, str]:
+    return {k: os.path.join(data_dir, f) for k, f in {
+        "messages": "messages.jsonl", "labels": "labels.jsonl",
+        "audit": "audit.jsonl", "silent": "silent.json", "report": "report.md",
+        "turns": "turns.jsonl", "dpo": "dpo.jsonl",
+        "rules": "rules.md", "rules_items": "rules-items.json", "rules_prompt": "rules-prompt.md",
+    }.items()}
+
+
+def _load_messages(path: str) -> dict[str, dict]:
+    if not os.path.exists(path):
+        sys.exit(f"{path} not found. Run `pushback extract` first.")
+    with open(path, encoding="utf-8") as fh:
+        return {m["id"]: m for m in map(json.loads, fh) if m}
+
+
+def cmd_extract(a):
+    p = _paths(a.data)
+    os.makedirs(a.data, exist_ok=True)
+    ex = extract_mod.extract(a.root, tuple(a.exclude or ()))
+    with open(p["messages"], "w", encoding="utf-8") as fh:
+        for m in ex.messages:
+            fh.write(json.dumps(m, ensure_ascii=False) + "\n")
+    with open(p["silent"], "w", encoding="utf-8") as fh:
+        json.dump({"rejections": ex.rejections, "interrupts": ex.interrupts}, fh)
+    with open(p["turns"], "w", encoding="utf-8") as fh:
+        for mid, t in ex.turns.items():
+            fh.write(json.dumps({"id": mid, **t}, ensure_ascii=False) + "\n")
+    print(f"{ex.sessions} sessions -> {len(ex.messages)} messages, "
+          f"{sum(ex.rejections.values())} rejected tool calls, {sum(ex.interrupts.values())} interrupts")
+    print(f"written to {a.data}/ (this folder holds your raw messages; keep it out of git)")
+
+
+def cmd_label(a):
+    p = _paths(a.data)
+    messages = list(_load_messages(p["messages"]).values())
+    base = os.environ.get("ANTHROPIC_BASE_URL")
+    print(f"Sending {len(messages)} messages to {base or 'the Anthropic API'} with model {a.model}.")
+    print("Your messages leave this machine for that provider. Check its data policy before using client logs.")
+    if not a.yes and input("Continue? [y/N] ").strip().lower() != "y":
+        sys.exit("aborted")
+    written, failed = label_mod.run(messages, p["labels"], a.model, a.batch_size, a.workers, a.effort)
+    print(f"done: {written} new labels, {failed} failed batches" + (" (re-run to retry them)" if failed else ""))
+
+
+def cmd_audit(a):
+    p = _paths(a.data)
+    messages = _load_messages(p["messages"])
+    labels = label_mod.load_labels(p["labels"])
+    if not labels:
+        sys.exit("no labels yet. Run `pushback label` first.")
+    n = audit_mod.run(messages, labels, p["audit"], a.n, a.seed)
+    print(f"\nsaved {n} answers to {p['audit']}")
+
+
+def cmd_report(a):
+    p = _paths(a.data)
+    labels = label_mod.load_labels(p["labels"])
+    if not labels:
+        sys.exit("no labels yet. Run `pushback label` first.")
+    silent = json.load(open(p["silent"], encoding="utf-8")) if os.path.exists(p["silent"]) else None
+    text = report_mod.render(report_mod.build(labels, audit_mod.load_audit(p["audit"]), silent))
+    print(text)
+    if a.markdown:
+        with open(p["report"], "w", encoding="utf-8") as fh:
+            fh.write(text + "\n")
+        print(f"\nwritten to {p['report']} (counts only, safe to share)")
+
+
+def cmd_export(a):
+    p = _paths(a.data)
+    messages = list(_load_messages(p["messages"]).values())
+    labels = label_mod.load_labels(p["labels"])
+    if not labels:
+        sys.exit("no labels yet. Run `pushback label` first.")
+    if not os.path.exists(p["turns"]):
+        sys.exit(f"{p['turns']} not found. Re-run `pushback extract` (it now saves full agent turns).")
+    with open(p["turns"], encoding="utf-8") as fh:
+        turns = {t["id"]: t for t in map(json.loads, fh)}
+    pairs, skipped = export_mod.build_pairs(
+        messages, labels, turns,
+        tasks=set(a.task) if a.task else None, ctypes=set(a.ctype) if a.ctype else None,
+        high_only=a.high_only, max_tools=a.max_tools,
+    )
+    redacted = export_mod.scrub(pairs)
+    if a.minimal:
+        pairs = [{k: x[k] for k in ("prompt", "chosen", "rejected")} for x in pairs]
+    out = a.out or p["dpo"]
+    with open(out, "w", encoding="utf-8") as fh:
+        for x in pairs:
+            fh.write(json.dumps(x, ensure_ascii=False) + "\n")
+    corrections = sum(1 for d in labels.values() if d["correction"])
+    print(f"{len(pairs)} pairs from {corrections} corrections -> {out}")
+    for reason, n in skipped.most_common():
+        print(f"  skipped {n}: {reason}")
+    print(f"  {redacted} likely secrets replaced with [REDACTED] (best effort: read the file before using it)")
+    print("This file holds raw agent and user text. It stays on your machine unless you move it.")
+
+
+def _default_existing() -> list[str]:
+    path = os.path.join(os.path.expanduser("~"), ".claude", "CLAUDE.md")
+    return [path] if os.path.exists(path) else []
+
+
+def cmd_rules(a):
+    p = _paths(a.data)
+    labels = label_mod.load_labels(p["labels"])
+    if not labels:
+        sys.exit("no labels yet. Run `pushback label` first.")
+
+    if a.from_response:
+        with open(p["rules_items"], encoding="utf-8") as fh:
+            items = json.load(fh)
+        with open(a.from_response, encoding="utf-8") as fh:
+            text = fh.read()
+        raw = json.loads(text[text.find("{"): text.rfind("}") + 1])  # tolerate prose or fences around the JSON
+    else:
+        if not os.path.exists(p["turns"]):
+            sys.exit(f"{p['turns']} not found. Re-run `pushback extract`.")
+        with open(p["turns"], encoding="utf-8") as fh:
+            turns = {t["id"]: t for t in map(json.loads, fh)}
+        items = rules_mod.collect(labels, turns, set(a.task) if a.task else None,
+                                  set(a.ctype) if a.ctype else None, a.limit)
+        if not items:
+            sys.exit("no corrections match those filters.")
+        existing_paths = a.existing if a.existing is not None else _default_existing()
+        existing = "\n".join(open(x, encoding="utf-8", errors="ignore").read() for x in existing_paths)
+        request = rules_mod.build_request(items, existing, a.model, a.effort)
+        with open(p["rules_items"], "w", encoding="utf-8") as fh:
+            json.dump(items, fh, ensure_ascii=False)
+        print(f"{len(items)} corrections, checked against {len(existing_paths)} existing rule file(s)")
+
+        if a.prompt_file:
+            with open(p["rules_prompt"], "w", encoding="utf-8") as fh:
+                fh.write(request["system"] + "\n\n" + request["messages"][0]["content"] + "\n\n"
+                         + "Reply with only a JSON object matching this schema:\n"
+                         + json.dumps(rules_mod.SCHEMA, indent=2) + "\n")
+            print(f"prompt written to {p['rules_prompt']}")
+            print("Give it to Claude (for example: ask Claude Code to answer the file), save the JSON reply,")
+            print("then run: pushback rules --from-response <reply file>")
+            return
+
+        base = os.environ.get("ANTHROPIC_BASE_URL")
+        print(f"Sending them to {base or 'the Anthropic API'} with model {a.model}.")
+        if not a.yes and input("Continue? [y/N] ").strip().lower() != "y":
+            sys.exit("aborted")
+        import anthropic
+        raw = rules_mod.ask(anthropic.Anthropic(), request)
+
+    found = rules_mod.parse(raw, items, a.min_support)
+    with open(p["rules"], "w", encoding="utf-8") as fh:
+        fh.write(rules_mod.render(found, len(items)))
+    broken = sum(1 for r in found if r["covered_by"])
+    print(f"{len(found)} rules ({broken} you already have but keep breaking) -> {p['rules']}")
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="pushback", description=__doc__)
+    ap.add_argument("--data", default=DATA, help=f"working folder (default: ./{DATA})")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("extract", help="pull your messages out of Claude Code transcripts")
+    e.add_argument("--root", default=extract_mod.DEFAULT_ROOT, help="transcripts folder")
+    e.add_argument("--exclude", nargs="*", help="session id prefixes to skip")
+    e.set_defaults(func=cmd_extract)
+
+    lb = sub.add_parser("label", help="label each message with Claude (resumable)")
+    lb.add_argument("--model", default=label_mod.DEFAULT_MODEL)
+    lb.add_argument("--effort", default="low", choices=["low", "medium", "high"])
+    lb.add_argument("--batch-size", type=int, default=40)
+    lb.add_argument("--workers", type=int, default=4)
+    lb.add_argument("-y", "--yes", action="store_true", help="skip the data-leaves-your-machine prompt")
+    lb.set_defaults(func=cmd_label)
+
+    au = sub.add_parser("audit", help="hand-check a sample so the report can bound the error")
+    au.add_argument("-n", type=int, default=40)
+    au.add_argument("--seed", type=int, default=0)
+    au.set_defaults(func=cmd_audit)
+
+    ex = sub.add_parser("export", help="write correction pairs as prompt/chosen/rejected JSONL")
+    ex.add_argument("--task", nargs="*", help="only these tasks, e.g. --task writing media")
+    ex.add_argument("--ctype", nargs="*",
+                    help="only these correction types; writing_content and tone_style make the cleanest pairs")
+    ex.add_argument("--high-only", action="store_true", help="only high-confidence labels")
+    ex.add_argument("--max-tools", type=int, help="drop pairs where either turn made more tool calls than this")
+    ex.add_argument("--minimal", action="store_true", help="only prompt/chosen/rejected (TRL DPO columns)")
+    ex.add_argument("--out", help="output path (default: <data>/dpo.jsonl)")
+    ex.set_defaults(func=cmd_export)
+
+    ru = sub.add_parser("rules", help="draft CLAUDE.md rules from your recurring corrections")
+    ru.add_argument("--task", nargs="*")
+    ru.add_argument("--ctype", nargs="*")
+    ru.add_argument("--limit", type=int, default=400, help="most recent N corrections (default 400)")
+    ru.add_argument("--min-support", type=int, default=3, help="corrections needed per rule (default 3)")
+    ru.add_argument("--existing", nargs="*", help="rule files to check against (default: ~/.claude/CLAUDE.md)")
+    ru.add_argument("--model", default=label_mod.DEFAULT_MODEL)
+    ru.add_argument("--effort", default="high", choices=["low", "medium", "high"])
+    ru.add_argument("--prompt-file", action="store_true", help="write the request to a file instead of calling the API")
+    ru.add_argument("--from-response", help="read the model's JSON reply from this file")
+    ru.add_argument("-y", "--yes", action="store_true")
+    ru.set_defaults(func=cmd_rules)
+
+    rp = sub.add_parser("report", help="print the correction-rate table")
+    rp.add_argument("--markdown", action="store_true", help="also write report.md")
+    rp.set_defaults(func=cmd_report)
+
+    args = ap.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()