kompactor 0.5.0__py3-none-any.whl

kompactor/outline.py

@@ -0,0 +1,274 @@
+"""Code skeletons, repo maps and symbol extraction - no dependencies.
+
+Python is parsed with `ast`; other languages use declaration regexes plus
+brace/indent matching, which is good enough for navigation (the agent can
+always Read the exact lines afterwards).
+"""
+
+import ast
+import os
+import re
+import subprocess
+from pathlib import Path
+
+SOURCE_EXT = {".py", ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".go", ".rs", ".java", ".kt", ".kts", ".scala",
+              ".swift", ".c", ".h", ".cc", ".cpp", ".hpp", ".cs", ".rb", ".php", ".lua", ".dart", ".sh", ".vue",
+              ".svelte", ".ex", ".exs"}
+
+DECL = re.compile(
+    r"^(?P<indent>\s*)(?:export\s+)?(?:default\s+)?(?:pub(?:\([^)]*\))?\s+)?(?:public\s+|private\s+|protected\s+|internal\s+"
+    r"|static\s+|abstract\s+|final\s+|override\s+|open\s+|sealed\s+|data\s+|async\s+|unsafe\s+|inline\s+|virtual\s+)*"
+    r"(?P<kind>class|interface|struct|enum|trait|impl|type|fn|func|function\*?|def|defp|defmodule|module|object|record"
+    r"|protocol|extension|namespace|const|let|var|val)\s+(?P<rest>.*)$")
+# Methods inside classes for JS/TS/Java/C#/Kotlin: `name(args) {` / `Type name(args) {`
+METHOD = re.compile(r"^(?P<indent>\s+)(?:(?:public|private|protected|static|async|override|get|set|readonly|final"
+                    r"|virtual|abstract|synchronized)\s+)*(?:[\w<>\[\],.?]+\s+)?(?P<name>#?[A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?"
+                    r"\([^;]*\)\s*(?::\s*[^={]+)?\s*(?:throws [\w., ]+)?\{?\s*$")
+NOT_METHOD = {"if", "for", "while", "switch", "catch", "return", "else", "do", "try", "function", "new", "await"}
+
+
+def _sig_py(node, src_lines):
+    strip = lambda ln: re.sub(r"\s+#.*$", "", ln).strip()  # noqa: E731  (drop trailing comments)
+    line = strip(src_lines[node.lineno - 1])
+    # include multi-line signatures up to the colon
+    i = node.lineno
+    while not line.endswith(":") and i < len(src_lines) and i < node.lineno + 8:
+        line += " " + strip(src_lines[i])
+        i += 1
+    return re.sub(r"\s+", " ", line)
+
+
+def outline_python(src: str):
+    tree = ast.parse(src)
+    lines = src.splitlines()
+    out = []
+
+    def walk(body, depth):
+        for n in body:
+            if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                doc = ast.get_docstring(n)
+                sig = "".join(f"@{ast.unparse(d)} " for d in n.decorator_list) + _sig_py(n, lines)
+                if doc:
+                    sig += f'  # {doc.strip().splitlines()[0][:80]}'
+                out.append((n.lineno, n.end_lineno, depth, sig))
+                if isinstance(n, ast.ClassDef):
+                    walk(n.body, depth + 1)
+            elif depth == 0 and isinstance(n, (ast.Assign, ast.AnnAssign)) and n.lineno == n.end_lineno:
+                txt = lines[n.lineno - 1].strip()
+                if re.match(r"^[A-Z_][A-Z0-9_]*\s*[:=]", txt):  # module constants only
+                    out.append((n.lineno, n.end_lineno, depth, txt[:120]))
+    walk(tree.body, 0)
+    return out
+
+
+def _depth(ws: str, unit: int) -> int:
+    return ws.count("\t") + ws.count(" ") // unit
+
+
+def outline_generic(src: str):
+    out = []
+    lines = src.splitlines()
+    spaces = [len(ln) - len(ln.lstrip(" ")) for ln in lines if ln.startswith(" ") and ln.strip()]
+    unit = min([n for n in spaces if n >= 2] or [4])
+    for i, ln in enumerate(lines, 1):
+        if len(ln) > 400:
+            continue
+        m = DECL.match(ln)
+        if m:
+            kind, indent = m.group("kind"), _depth(m.group("indent"), unit)
+            if (kind in ("const", "let", "var", "val") and indent > 0) or ln.rstrip().endswith(","):
+                continue
+            if kind in ("const", "let", "var", "val") and not re.search(r"=\s*(async\s*)?(\(|function|\w+\s*=>|class|\{$|\[$|new |require|import|styled|create)", ln):
+                if not re.match(r"^\s*(export\s+)?const [A-Z_][A-Z0-9_]*\s*[=:]", ln):
+                    continue
+            out.append((i, _block_end(lines, i), indent, _clip(ln)))
+            continue
+        mm = METHOD.match(ln)
+        if mm and mm.group("name") not in NOT_METHOD and ln.rstrip().endswith("{"):
+            out.append((i, _block_end(lines, i), _depth(mm.group("indent"), unit), _clip(ln)))
+    return out
+
+
+def _clip(ln: str) -> str:
+    s = ln.strip().rstrip("{").rstrip()
+    return s if len(s) <= 160 else s[:157] + "..."
+
+
+def _block_end(lines, start):
+    """1-based end line of the block starting at `start` (brace or indent based)."""
+    depth, seen = 0, False
+    for j in range(start - 1, min(len(lines), start + 5000)):
+        code = re.sub(r"(\"(\\.|[^\"\\])*\"|'(\\.|[^'\\])*'|`[^`]*`|//.*$)", "", lines[j])
+        depth += code.count("{") - code.count("}")
+        seen |= "{" in code
+        if seen and depth <= 0:
+            return j + 1
+        if not seen and code.rstrip().endswith(";"):
+            return j + 1
+        if not seen and j >= start:  # no brace on the declaration line or the next one
+            break
+    # indentation-based languages (ruby/elixir/lua `end`, or none)
+    base = len(lines[start - 1]) - len(lines[start - 1].lstrip())
+    for j in range(start, len(lines)):
+        s = lines[j]
+        if s.strip() and len(s) - len(s.lstrip()) <= base:
+            return j + (1 if s.strip() in ("end", "}", "};") else 0)
+    return len(lines)
+
+
+def outline(path: str, src: str = None):
+    """List of (start, end, depth, signature) for a file."""
+    if src is None:
+        src = Path(path).read_text(errors="replace")
+    if path.endswith(".py"):
+        try:
+            return outline_python(src)
+        except SyntaxError:
+            pass
+    return outline_generic(src)
+
+
+def render_outline(path: str, src: str = None, max_items: int = 400) -> str:
+    items = outline(path, src)
+    rows = [f"{'  ' * d}{sig}  [L{s}-{e}]" if e and e > s else f"{'  ' * d}{sig}  [L{s}]"
+            for s, e, d, sig in items[:max_items]]
+    if len(items) > max_items:
+        rows.append(f"… +{len(items) - max_items} more symbols")
+    return "\n".join(rows)
+
+
+# ---------------------------------------------------------------------------
+# repo map
+
+
+IGNORE_DIRS = {".git", "node_modules", "dist", "build", "out", "target", "vendor", ".venv", "venv", "__pycache__",
+               ".next", ".nuxt", "coverage", ".mypy_cache", ".pytest_cache", ".tox", ".idea", ".gradle"}
+
+
+def list_files(root: str):
+    try:
+        res = subprocess.run(["git", "ls-files", "-co", "--exclude-standard"], cwd=root, capture_output=True,
+                             text=True, timeout=20)
+        if res.returncode == 0:
+            return [f for f in res.stdout.splitlines() if f]
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    files = []
+    for d, dirs, fs in os.walk(root):
+        dirs[:] = [x for x in dirs if x not in IGNORE_DIRS and not x.startswith(".")]
+        files += [os.path.relpath(os.path.join(d, f), root) for f in fs]
+    return files
+
+
+TESTY = re.compile(r"(^|/)(tests?|__tests__|test-d|spec|specs|fixtures?|examples?|e2e|benchmarks?)(/|$)|[._-](test|spec)\.\w+$|(^|/)test_[^/]+$")
+
+
+def _mappable(path: str, sig: str) -> bool:
+    """In JS/TS only exported values make the map; locals are noise there."""
+    if Path(path).suffix in (".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs") and re.match(r"(const|let|var)\s", sig):
+        return False
+    return True
+
+
+def repo_map(root: str = ".", budget_tokens: int = 4000, depth_limit: int = 1) -> str:
+    """Compact map of every source file's top-level symbols, trimmed to a token budget.
+
+    Files are ordered by how often their symbols are referenced elsewhere (a cheap
+    PageRank stand-in), so the most central code survives trimming.
+    """
+    from . import tokens
+
+    files = [f for f in list_files(root) if Path(f).suffix in SOURCE_EXT]
+    entries, words = [], {}
+    for f in files:
+        p = os.path.join(root, f)
+        try:
+            if os.path.getsize(p) > 400_000:
+                continue
+            src = Path(p).read_text(errors="replace")
+        except OSError:
+            continue
+        words[f] = set(re.findall(r"[A-Za-z_]\w{3,}", src))
+        items = [it for it in outline(f, src) if it[2] <= depth_limit and _mappable(f, it[3])]
+        entries.append((f, items))
+
+    # rank files by how many *other* files reference the symbols they define
+    defined = {}
+    for f, items in entries:
+        for _, _, _, sig in items:
+            m = re.search(r"(?:def|class|function|func|fn|interface|struct|type|enum|trait|const|let|var)\s+\*?([A-Za-z_]\w{3,})", sig)
+            if m:
+                defined.setdefault(m.group(1), set()).add(f)
+    score = {f: 0.0 for f, _ in entries}
+    for name, owners in defined.items():
+        users = sum(1 for f, ws in words.items() if name in ws and f not in owners)
+        for f in owners:
+            score[f] += users
+    for f in score:
+        if TESTY.search(f):
+            score[f] = score[f] * 0.05 - 1
+
+    entries.sort(key=lambda e: (-score[e[0]], e[0]))
+    out, used = [], 0
+    skipped = []
+    for f, items in entries:
+        block = [f"{f}:"] + [f"  {'  ' * d}{sig}" for _, _, d, sig in items[:60]]
+        if len(items) > 60:
+            block.append(f"  … +{len(items) - 60} more")
+        cost = tokens.count("\n".join(block))
+        if used + cost > budget_tokens and out:
+            skipped.append(f)
+            continue
+        out += block
+        used += cost
+    if skipped:
+        out.append(f"[{len(skipped)} lower-ranked files omitted to fit budget: {', '.join(skipped[:15])}"
+                   f"{' …' if len(skipped) > 15 else ''}]")
+    return "\n".join(out)
+
+
+# ---------------------------------------------------------------------------
+# symbol lookup
+
+
+NAME = re.compile(r"\b(?:def|class|function\*?|func|fn|interface|struct|type|enum|trait|const|let|var|val|impl|module"
+                  r"|object|record|protocol|namespace|defp?|defmodule)\s+(?:\([^)]*\)\s*)?\*?([A-Za-z_$][\w$.]*)")
+
+
+def _name(sig: str):
+    sig = re.sub(r"^(@\S+(\([^)]*\))?\s+)+", "", sig)
+    m = NAME.search(sig)
+    if m:
+        return m.group(1).split(".")[-1]
+    m = re.match(r"^(?:[\w<>\[\],.?]+\s+)*([A-Za-z_$][\w$]*)\s*(?:<[^>]*>)?\(", sig)
+    return m.group(1) if m else None
+
+
+def find_symbol(name: str, root: str = ".", paths=None, max_hits: int = 5):
+    """Yield (file, start, end, source) for definitions named `name` (supports Class.method)."""
+    parts = name.split(".")
+    leaf = parts[-1]
+    hits = []
+    for f in paths or list_files(root):
+        if Path(f).suffix not in SOURCE_EXT:
+            continue
+        p = f if os.path.isabs(f) else os.path.join(root, f)
+        try:
+            src = Path(p).read_text(errors="replace")
+        except OSError:
+            continue
+        if leaf not in src:
+            continue
+        lines = src.splitlines()
+        items = outline(f, src)
+        for idx, (s, e, d, sig) in enumerate(items):
+            if _name(sig) != leaf:
+                continue
+            if len(parts) > 1:  # require an enclosing parent with the given name
+                parents = [it for it in items[:idx] if it[2] < d and it[0] <= s <= (it[1] or s)]
+                if not parents or parts[-2] not in parents[-1][3]:
+                    continue
+            hits.append((f, s, e, "\n".join(lines[s - 1:e])))
+            if len(hits) >= max_hits:
+                return hits
+    return hits

kompactor/prove.py

@@ -0,0 +1,317 @@
+"""A/B proof: run the same Claude Code tasks with and without Kompactor.
+
+    kompactor prove --tasks bench/tasks.json --repos /path/to/checkouts [--reps 1] [--preset 3]
+
+Each task runs through headless `claude -p` in both conditions with identical
+prompts, tools, turn limits and budget caps. The only difference is Kompactor's
+hooks, passed with --settings. Every run gets a fresh session id and its own
+Kompactor data folder, so no state leaks between runs. Recorded per run: tokens
+(input + cache writes + cache reads + output, as Claude Code bills them), cost,
+turns, wall time, whether the answer contains the expected facts, and Kompactor's
+own ledger. Writes results.json and REPORT.md to --out.
+"""
+
+import argparse
+import json
+import os
+import shlex
+import sqlite3
+import statistics
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+
+from . import __version__, config, installer
+
+
+PLUGIN_ROOT = Path(__file__).resolve().parent.parent
+
+
+def hook_settings() -> dict:
+    cmd = installer.launcher()
+    hooks = {}
+    for event, matcher, handler in installer.HOOKS:
+        entry = {"hooks": [{"type": "command", "command": f"{cmd} hook {handler}", "timeout": 15}]}
+        hooks.setdefault(event, []).append({"matcher": matcher, **entry} if matcher else entry)
+    return {"hooks": hooks}
+
+
+def _setup(repo: Path, steps, undo=False):
+    for step in steps or []:
+        if step[0] == "write":
+            p = repo / step[1]
+            if undo:
+                p.unlink(missing_ok=True)
+            else:
+                p.parent.mkdir(parents=True, exist_ok=True)
+                p.write_text(step[2])
+
+
+def _ledger(home: Path) -> dict:
+    db = home / "kompactor.db"
+    if not db.exists():
+        return {"events": 0, "saved": 0, "by_feature": {}}
+    c = sqlite3.connect(db)
+    try:
+        rows = c.execute("SELECT feature, COUNT(*), SUM(raw_tokens - kept_tokens) FROM events GROUP BY feature").fetchall()
+    finally:
+        c.close()
+    return {"events": sum(r[1] for r in rows), "saved": sum(r[2] or 0 for r in rows),
+            "by_feature": {r[0]: {"count": r[1], "saved": r[2]} for r in rows}}
+
+
+def _tool_trace(session_id: str) -> list:
+    """Tool calls Claude made in a run and how big each result was, from its transcript."""
+    files = list(Path.home().glob(f".claude/projects/*/{session_id}.jsonl"))
+    if not files:
+        return []
+    uses, out = {}, []
+    for line in files[0].read_text(errors="replace").splitlines():
+        try:
+            d = json.loads(line)
+        except ValueError:
+            continue
+        m = d.get("message")
+        content = m.get("content") if isinstance(m, dict) else None
+        for b in content if isinstance(content, list) else []:
+            if b.get("type") == "tool_use":
+                inp = b.get("input") or {}
+                uses[b.get("id")] = (b.get("name"), inp.get("command") or inp.get("file_path") or inp.get("pattern") or "")
+            elif b.get("type") == "tool_result" and b.get("tool_use_id") in uses:
+                c = b.get("content")
+                text = c if isinstance(c, str) else json.dumps(c)
+                name, arg = uses[b["tool_use_id"]]
+                out.append({"tool": name, "arg": str(arg)[:160], "result_chars": len(text),
+                            "kompactor": "[kompactor" in text})
+    return out
+
+
+def run_once(task: dict, repo: Path, condition: str, work: Path, preset: int, model=None, budget=1.0,
+             overrides=None) -> dict:
+    run_dir = work / f"{task['id']}-{condition}-{uuid.uuid4().hex[:6]}"
+    home = run_dir / "kompactor"
+    home.mkdir(parents=True)
+    env = dict(os.environ, KOMPACTOR_HOME=str(home))
+    env.pop(installer.PREFIX_ENV, None)
+    env.pop("CLAUDE_CODE_SESSION_ID", None)  # when run from inside Claude Code; each run has its own session
+    tools = list(task["tools"])
+    session_id = str(uuid.uuid4())
+    args = ["claude", "-p", task["prompt"], "--output-format", "json", "--max-turns", str(task.get("max_turns", 10)),
+            "--session-id", session_id, "--max-budget-usd", str(budget), "--strict-mcp-config"]
+    if condition == "kompactor":
+        (home / "config.json").write_text(json.dumps({"preset": preset, "overrides": overrides or {}}))
+        if (PLUGIN_ROOT / ".claude-plugin" / "plugin.json").exists():  # exactly what a plugin user gets: hooks + skill
+            args += ["--plugin-dir", str(PLUGIN_ROOT)]
+        else:
+            settings = run_dir / "settings.json"
+            settings.write_text(json.dumps(hook_settings()))
+            args += ["--settings", str(settings)]
+        tools += sorted({"Bash(kompactor:*)", f"Bash({installer.cli_name()}:*)"})
+        prefix = run_dir / "kompactor-shell"  # what `kompactor setup` installs as ~/.kompactor/bin/kompactor-shell
+        prefix.write_text(installer.SHELL_PREFIX.format(py=shlex.quote(sys.executable or "python3"),
+                                                        script=shlex.quote(str(Path(installer.__file__).with_name("_launch.py")))))
+        prefix.chmod(0o755)
+        env[installer.PREFIX_ENV] = str(prefix)
+    args += ["--allowedTools", ",".join(tools)]
+    if model:
+        args += ["--model", model]
+    t0 = time.time()
+    p = subprocess.run(args, cwd=repo, env=env, capture_output=True, text=True, timeout=1200,
+                       stdin=subprocess.DEVNULL)
+    wall = time.time() - t0
+    try:
+        data = json.loads(p.stdout)
+    except ValueError:
+        data = {"is_error": True, "result": (p.stdout or p.stderr)[-500:]}
+    if data.get("is_error") and not data.get("num_turns"):
+        raise RuntimeError(f"claude failed to start ({task['id']}, {condition}): {(p.stderr or p.stdout)[-300:]}")
+    usage = data.get("usage") or {}
+    by_model = data.get("modelUsage") or {}
+    if by_model:  # includes helper models Claude Code used during the run
+        tok = {k: sum(m.get(k, 0) or 0 for m in by_model.values()) for k in
+               ("inputTokens", "outputTokens", "cacheReadInputTokens", "cacheCreationInputTokens")}
+        tokens = {"input": tok["inputTokens"], "output": tok["outputTokens"], "cache_read": tok["cacheReadInputTokens"],
+                  "cache_write": tok["cacheCreationInputTokens"]}
+    else:
+        tokens = {"input": usage.get("input_tokens", 0), "output": usage.get("output_tokens", 0),
+                  "cache_read": usage.get("cache_read_input_tokens", 0),
+                  "cache_write": usage.get("cache_creation_input_tokens", 0)}
+    tokens["total"] = sum(tokens.values())
+    answer = data.get("result") or ""
+    missing = [e for e in task.get("expect", []) if e.lower() not in answer.lower()]
+    return {"task": task["id"], "lang": task.get("lang", ""), "condition": condition, "tokens": tokens,
+            "cost": data.get("total_cost_usd", 0) or 0, "turns": data.get("num_turns", 0), "wall_s": round(wall, 1),
+            "correct": not missing and not data.get("is_error"), "missing": missing, "error": bool(data.get("is_error")),
+            "subtype": data.get("subtype", ""), "models": sorted(by_model), "answer": answer[:1500],
+            "tools": _tool_trace(session_id), "kompactor": _ledger(home) if condition == "kompactor" else None}
+
+
+def summarize(results: list) -> dict:
+    out = {}
+    for r in results:
+        out.setdefault(r["task"], {"lang": r["lang"], "baseline": [], "kompactor": []})[r["condition"]].append(r)
+    rows = []
+    for task, d in out.items():
+        b, k = d["baseline"], d["kompactor"]
+        if not b or not k:
+            continue
+        mean = lambda rs, f: statistics.mean(f(r) for r in rs)  # noqa: E731
+        rows.append({
+            "task": task, "lang": d["lang"], "runs": len(b),
+            "base_tokens": mean(b, lambda r: r["tokens"]["total"]), "k_tokens": mean(k, lambda r: r["tokens"]["total"]),
+            "base_range": (min(r["tokens"]["total"] for r in b), max(r["tokens"]["total"] for r in b)),
+            "k_range": (min(r["tokens"]["total"] for r in k), max(r["tokens"]["total"] for r in k)),
+            "base_tool_chars": mean(b, lambda r: sum(t["result_chars"] for t in r.get("tools", []))),
+            "k_tool_chars": mean(k, lambda r: sum(t["result_chars"] for t in r.get("tools", []))),
+            "base_cost": mean(b, lambda r: r["cost"]), "k_cost": mean(k, lambda r: r["cost"]),
+            "base_turns": mean(b, lambda r: r["turns"]), "k_turns": mean(k, lambda r: r["turns"]),
+            "base_output": mean(b, lambda r: r["tokens"]["output"]), "k_output": mean(k, lambda r: r["tokens"]["output"]),
+            "base_correct": sum(r["correct"] for r in b), "k_correct": sum(r["correct"] for r in k),
+            "k_saved_ledger": mean(k, lambda r: (r["kompactor"] or {}).get("saved", 0)),
+            "k_events": mean(k, lambda r: (r["kompactor"] or {}).get("events", 0)),
+        })
+    return {"rows": rows}
+
+
+def _pct(a, b):
+    return f"{100 * (b - a) / a:+.0f}%" if a else "n/a"
+
+
+def report_md(results: list, meta: dict) -> str:
+    rows = summarize(results)["rows"]
+    tb = sum(r["base_tokens"] for r in rows)
+    tk = sum(r["k_tokens"] for r in rows)
+    cb = sum(r["base_cost"] for r in rows)
+    ck = sum(r["k_cost"] for r in rows)
+    ob = sum(r["base_output"] for r in rows)
+    ok = sum(r["k_output"] for r in rows)
+    lines = [
+        "# Kompactor A/B evidence",
+        "",
+        f"Real headless Claude Code sessions (`claude -p`, Claude Code {meta.get('claude_version', '?')}, "
+        f"model {', '.join(meta.get('models', [])) or 'default'}), Kompactor {meta['kompactor_version']} at level "
+        f"{meta['preset']} ({config.PRESETS[meta['preset']]['name']}). {meta['reps']} run(s) per task and condition; "
+        f"same prompt, tools, turn limit and budget cap in both conditions. Generated {meta['date']}.",
+        "",
+        f"**Total across {len(rows)} tasks: {tb:,.0f} › {tk:,.0f} tokens ({_pct(tb, tk)}), "
+        f"cost ${cb:.2f} › ${ck:.2f} ({_pct(cb, ck)}), output tokens {_pct(ob, ok)}. "
+        f"Correct answers: {sum(r['base_correct'] for r in rows)}/{sum(r['runs'] for r in rows)} without, "
+        f"{sum(r['k_correct'] for r in rows)}/{sum(r['runs'] for r in rows)} with Kompactor.**",
+        "",
+        "| Task | Lang | Tokens without (min–max) | Tokens with (min–max) | Δ tokens | Cost without | Cost with | Δ cost "
+        "| Tool output chars | Turns | Correct |",
+        "|---|---|---:|---:|---:|---:|---:|---:|---|---|---|",
+    ]
+    for r in rows:
+        lines.append(f"| {r['task']} | {r['lang']} | {r['base_tokens']:,.0f} ({r['base_range'][0] / 1000:.0f}k–"
+                     f"{r['base_range'][1] / 1000:.0f}k) | {r['k_tokens']:,.0f} ({r['k_range'][0] / 1000:.0f}k–"
+                     f"{r['k_range'][1] / 1000:.0f}k) | {_pct(r['base_tokens'], r['k_tokens'])} | ${r['base_cost']:.3f} | "
+                     f"${r['k_cost']:.3f} | {_pct(r['base_cost'], r['k_cost'])} | {r['base_tool_chars'] / 1000:.1f}k › "
+                     f"{r['k_tool_chars'] / 1000:.1f}k | {r['base_turns']:.1f} › {r['k_turns']:.1f} | "
+                     f"{r['base_correct']}/{r['runs']} › {r['k_correct']}/{r['runs']} |")
+    lines += ["", "Tokens = input + cache writes + cache reads + output, summed over every API call in the session "
+              "(what Claude Code bills). Δ is relative to the run without Kompactor. Correct means the final answer "
+              "contained every expected fact (see `bench/tasks.json`).", "",
+              "## What happened in each run", "",
+              "Tool calls Claude made (from the session transcript), result size, and what Kompactor changed.", ""]
+    for r in sorted(results, key=lambda r: (r["task"], r["condition"])):
+        calls = "; ".join(f"{t['tool']} {t['arg'][:60]} ({t['result_chars']:,} chars{', compacted' if t['kompactor'] else ''})"
+                          for t in r.get("tools", [])[:6]) or "no tool calls"
+        led = ""
+        if r["condition"] == "kompactor" and r["kompactor"]:
+            led = " · Kompactor: " + (", ".join(f"{f} ×{v['count']} (−{v['saved']:,} tokens)"
+                                              for f, v in r["kompactor"]["by_feature"].items()) or "nothing to compact")
+        lines.append(f"- **{r['task']} · {r['condition']}** ({r['tokens']['total']:,} tokens, {r['turns']} turns): "
+                     f"{calls}{led}")
+    lines += ["", "## Answers", ""]
+    for r in results:
+        lines.append(f"<details><summary>{r['task']} · {r['condition']} · "
+                     f"{'correct' if r['correct'] else 'missing ' + ', '.join(r['missing'])}</summary>\n\n"
+                     f"```\n{r['answer'].strip()[:1200]}\n```\n</details>\n")
+    return "\n".join(lines)
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="kompactor prove", description=__doc__.split("\n\n")[0])
+    ap.add_argument("--tasks", required=True)
+    ap.add_argument("--repos", required=True, help="folder containing the task repos")
+    ap.add_argument("--out", default="evidence")
+    ap.add_argument("--reps", type=int, default=1)
+    ap.add_argument("--preset", type=int, default=3)
+    ap.add_argument("--only", help="comma-separated task ids")
+    ap.add_argument("--model")
+    ap.add_argument("--budget", type=float, default=1.0, help="max USD per run (passed to claude)")
+    ap.add_argument("--parallel", type=int, default=1, help="tasks to run at the same time")
+    ap.add_argument("--report", action="store_true", help="rewrite REPORT.md from the saved results, run nothing")
+    ap.add_argument("--set", action="append", default=[], metavar="KEY=VALUE",
+                    help="override a Kompactor setting for the runs, e.g. --set bash_plain=true")
+    a = ap.parse_args(argv)
+    tasks = json.loads(Path(a.tasks).read_text())["tasks"]
+    overrides = {}
+    for kv in a.set:
+        k, _, v = kv.partition("=")
+        overrides[k] = config.coerce(k, v)
+    if a.only:
+        keep = set(a.only.split(","))
+        tasks = [t for t in tasks if t["id"] in keep]
+    out = Path(a.out).resolve()  # claude runs inside each repo, so every path must be absolute
+    out.mkdir(parents=True, exist_ok=True)
+    work = out / "runs"
+    work.mkdir(exist_ok=True)
+    results_file = out / "results.json"
+    results = json.loads(results_file.read_text())["results"] if results_file.exists() else []
+    for r in results:  # runs recorded before the rename from Kompact
+        if "kompact" in r:
+            r.setdefault("kompactor", r.pop("kompact"))
+        for t in r.get("tools", []):
+            if "kompact" in t:
+                t.setdefault("kompactor", t.pop("kompact"))
+    if a.report:
+        meta = json.loads(results_file.read_text()).get("meta", {}) if results_file.exists() else {}
+        results_file.write_text(json.dumps({"meta": meta, "results": results}, indent=1))
+        (out / "REPORT.md").write_text(report_md(results, meta))
+        print((out / "REPORT.md").read_text().split("\n\n|")[0])
+        return 0
+    claude_version = subprocess.run(["claude", "--version"], capture_output=True, text=True).stdout.strip()
+    lock = threading.Lock()
+    have = {}
+    for r in results:
+        have[(r["task"], r["condition"])] = have.get((r["task"], r["condition"]), 0) + 1
+
+    def do_task(task):
+        repo = Path(a.repos, task["repo"]).resolve()
+        with lock:
+            _setup(repo, task.get("setup"))
+        try:
+            for rep in range(a.reps):
+                for condition in ("baseline", "kompactor"):  # interleaved so drift affects both equally
+                    if have.get((task["id"], condition), 0) > rep:
+                        continue
+                    r = run_once(task, repo, condition, work, a.preset, a.model, a.budget, overrides)
+                    with lock:
+                        results.append(r)
+                        results_file.write_text(json.dumps({"results": results}, indent=1))
+                        print(f"[prove] {task['id']} · {condition} · run {rep + 1}: {r['tokens']['total']:,} tokens · "
+                              f"${r['cost']:.3f} · {r['turns']} turns · "
+                              f"{'correct' if r['correct'] else 'MISSING ' + ', '.join(r['missing'])}", flush=True)
+        finally:
+            with lock:
+                _setup(repo, task.get("setup"), undo=True)
+
+    with ThreadPoolExecutor(max_workers=max(1, a.parallel)) as pool:
+        list(pool.map(do_task, tasks))
+    meta = {"kompactor_version": __version__, "preset": a.preset, "overrides": overrides, "reps": a.reps,
+            "claude_version": claude_version,
+            "models": sorted({m for r in results for m in r.get("models", [])}), "date": time.strftime("%Y-%m-%d")}
+    results_file.write_text(json.dumps({"meta": meta, "results": results}, indent=1))
+    (out / "REPORT.md").write_text(report_md(results, meta))
+    print((out / "REPORT.md").read_text().split("\n\n|")[0])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kompactor/rules.py

@@ -0,0 +1,54 @@
+"""Reply-style rules injected at session start (and into subagents).
+
+Two independent dials, kept deliberately short because these tokens are paid
+on every turn (caveman's rules cost ~1,160; these cost ~20-160). Kompactor's own
+commands aren't advertised here: compacted output and outlines say how to get
+the full text, and the code map (given on first exploration) names the graph.
+
+- prose: off | lite | full | ultra   (caveman / claude-token-efficient lineage)
+- code:  normal | lean | strict      (ponytail lineage: reuse first, smallest diff)
+
+Code, commands, paths, errors, numbers, negations and security warnings are
+never shortened, and commit messages and docs stay normal prose.
+"""
+
+ANSWER_FIRST = "Lead with the answer; no preamble, recap, restated question or praise."
+PROSE = {
+    "off": [],
+    "lite": [ANSWER_FIRST],
+    "full": [ANSWER_FIRST, "Short sentences, fragments fine, lists over paragraphs; no narration between tool calls."],
+    "ultra": [ANSWER_FIRST, "Telegraphic: one line per point, articles optional, no narration. Explain only if asked."],
+}
+
+LEAN = [
+    "Before editing, check callers, tests and config (`{cli} graph impact <file|symbol>`).",
+    "Prefer no change, then reuse (codebase, stdlib, installed packages), then the smallest diff. Fix root causes.",
+    "No unrequested abstractions, options or refactors; one focused test for non-trivial logic.",
+    "Never trade away validation, error handling, security or accessibility.",
+]
+CODE = {
+    "normal": [],
+    "lean": LEAN,
+    "strict": LEAN + ["If a smaller alternative would do, propose it first. Mark deliberate limits `shortcut: <limit>`."],
+}
+
+KEEP = "Keep code, commands, paths, errors, numbers and warnings exact; commits and docs stay normal prose."
+
+PLAIN = ("Run tests, builds and linters plainly, without | head, | tail or | grep: Kompactor keeps every failure, "
+         "so one run is enough.")
+
+
+def build(prose: str = "lite", code: str = "lean", cli: str = "kompactor", plain: bool = False) -> str:
+    lines = list(PROSE.get(prose, []))
+    if lines:
+        lines.append(KEEP)
+    lines += CODE.get(code, [])
+    if plain:
+        lines.append(PLAIN)
+    if not lines:
+        return ""
+    return "[kompactor]\n" + "\n".join(f"- {ln.format(cli=cli)}" for ln in lines)
+
+
+# Back-compat for callers that look up a style by name.
+STYLES = {name: build(name, "normal") for name in PROSE}