consequence-ledger 0.3.0__py3-none-any.whl

ledger/cli.py

@@ -0,0 +1,637 @@
+"""Command-line interface: python -m ledger <command>."""
+import argparse
+import datetime as dt
+import json
+import sys
+import tempfile
+from contextlib import closing
+from pathlib import Path
+
+from . import __version__
+from . import report as report_mod
+from .db import connect, db_path
+from .estimate import DEFAULT_FOLDS, MIN_CROSSFIT, early_readout, estimate, load_rows, merge_balance
+from .gitio import GitError, branch_key, current_branch, git, repo_root, safe_rev
+from .label import DEFAULT_MAX_BLAMED, label
+from .policy import record_decision
+from .segments import breakdown, recommend
+
+DETACHED = "(detached HEAD)"
+HOOK_MARKER = "consequence-ledger hook v2"
+HOOK = f"""#!/bin/sh
+# {HOOK_MARKER}: tag commits with the decision that is active on the current branch.
+# Finds the shared ledger from any worktree; does nothing where no decision is active.
+[ "$2" = "merge" ] && exit 0
+common="$(git rev-parse --git-common-dir 2>/dev/null)" || exit 0
+root="$(cd "$common" 2>/dev/null && pwd)" || exit 0
+branch="$(git symbolic-ref --short -q HEAD)" || branch="(detached HEAD)"
+key="$(printf '%s' "$branch" | git hash-object --stdin)"
+f="$(dirname "$root")/.ledger/active/$key"
+[ -f "$f" ] || exit 0
+id="$(head -n 1 "$f")"
+grep -q "^Ledger-Decision-Id:" "$1" && exit 0
+git interpret-trailers --in-place --trailer "Ledger-Decision-Id: $id" "$1"
+"""
+
+
+class CliError(Exception):
+    """A problem the user can fix; shown as one line without a traceback."""
+
+
+def parse_date(value):
+    if value is None:
+        return None
+    if value.isdigit():
+        return int(value)
+    try:
+        d = dt.datetime.fromisoformat(value)
+    except ValueError:
+        raise CliError(f"could not read the date {value!r}; use 2026-06-30, 2026-06-30T12:00:00Z or unix seconds") from None
+    if d.tzinfo is None:
+        d = d.replace(tzinfo=dt.timezone.utc)
+    return int(d.timestamp())
+
+
+def ledger_dir(repo):
+    return Path(repo) / ".ledger"
+
+
+def need_ledger(repo):
+    """Commands that read or write decisions refuse to run, and litter, where no ledger exists."""
+    if not db_path(repo).exists():
+        raise CliError(f"no ledger in {Path(repo).resolve()}: run `ledger init` in the repository first")
+
+
+def friendly_git_error(e, repo):
+    text = str(e)
+    if "not a git repository" in text:
+        return f"{Path(repo).resolve()} is not a git repository"
+    if any(s in text for s in ("unknown revision", "ambiguous argument", "bad revision", "does not have any commits")):
+        return "this repository has no commits yet, or the revision you gave does not exist"
+    return text
+
+
+def write_json(path, data):
+    Path(path).write_text(json.dumps(data, indent=2, default=str))
+
+
+def active_dir(repo):
+    return ledger_dir(repo) / "active"
+
+
+def workdir(args):
+    """The folder the user ran the command from; its checked-out branch decides which decision applies."""
+    return getattr(args, "workdir", args.repo)
+
+
+def cmd_init(args):
+    git(args.repo, "rev-parse", "--git-dir")  # a clear error if this is not a repository
+    repo = Path(args.repo)
+    connect(db_path(repo)).close()
+    legacy = ledger_dir(repo) / "current_decision"   # v1 kept one decision per repository
+    legacy.unlink(missing_ok=True)
+    hooks = Path(git(repo, "rev-parse", "--git-path", "hooks").strip())
+    hooks = hooks if hooks.is_absolute() else repo / hooks
+    hooks.mkdir(parents=True, exist_ok=True)
+    hook = hooks / "prepare-commit-msg"
+    existing = hook.read_text(encoding="utf-8", errors="replace") if hook.exists() else ""
+    if existing and "consequence-ledger" not in existing:
+        print(f"warning: {hook} exists; add the Ledger-Decision-Id trailer step yourself", file=sys.stderr)
+    else:
+        # Always LF: git's sh can't run a script with CRLF line endings. (Path.write_text(newline=) needs 3.10.)
+        with open(hook, "w", encoding="utf-8", newline="\n") as f:
+            f.write(HOOK)
+        hook.chmod(0o755)
+        if existing and HOOK_MARKER not in existing:
+            print("upgraded the commit hook: decisions are now tracked per branch")
+    print(f"ledger ready in {ledger_dir(repo)}")
+
+
+def cmd_decide(args):
+    need_ledger(args.repo)
+    arms = [a.strip() for a in args.arms.split(",") if a.strip()]
+    if len(arms) < 2 or len(set(arms)) != len(arms):
+        raise CliError("--arms needs at least two different names, e.g. --arms claude-code,codex")
+    try:
+        scores = [float(s) for s in args.scores.split(",")] if args.scores else None
+    except ValueError:
+        raise CliError("--scores must be numbers separated by commas, one per arm, e.g. --scores 1.0,0.5") from None
+    if scores is not None and len(scores) != len(arms):
+        raise CliError(f"--scores has {len(scores)} values but --arms has {len(arms)}; give one score per arm")
+    try:
+        context = json.loads(args.context)
+    except ValueError:
+        raise CliError("""--context must be JSON, e.g. --context '{"stratum": "hard"}'""") from None
+    if not isinstance(context, dict):
+        raise CliError("--context must be a JSON object such as {\"stratum\": \"hard\"}")
+    branch = current_branch(workdir(args))
+    with closing(connect(db_path(args.repo))) as con:
+        d = record_decision(con, arms, scores, context, args.epsilon, args.temperature, args.policy_version)
+        con.commit()
+    # One active decision per branch, so parallel agents on parallel branches or worktrees never share one.
+    active = active_dir(args.repo)
+    active.mkdir(parents=True, exist_ok=True)
+    with open(active / branch_key(branch), "w", encoding="utf-8", newline="\n") as f:
+        f.write(f"{d['id']}\n{branch or DETACHED}\n")
+    print(json.dumps({**d, "branch": branch or DETACHED}, indent=2))
+
+
+def cmd_done(args):
+    active = active_dir(args.repo)
+    if args.all:
+        files = list(active.glob("*")) if active.exists() else []
+        for f in files:
+            f.unlink()
+        print(f"cleared {len(files)} active decision(s); new commits will not be tagged")
+        return
+    branch = current_branch(workdir(args))
+    target = active / branch_key(branch)
+    existed = target.exists()
+    target.unlink(missing_ok=True)
+    name = branch or DETACHED
+    print(f"no active decision on {name}; new commits there will not be tagged" if existed
+          else f"{name} had no active decision")
+
+
+def cmd_attach(args):
+    need_ledger(args.repo)
+    try:
+        sha = git(args.repo, "rev-parse", "--verify", safe_rev(args.commit) + "^{commit}").strip()
+    except GitError:
+        raise CliError(f"no commit matches {args.commit!r} in this repository") from None
+    ts = int(git(args.repo, "show", "-s", "--format=%ct", sha).strip())
+    with closing(connect(db_path(args.repo))) as con:
+        if not con.execute("SELECT 1 FROM decisions WHERE id=?", (args.decision,)).fetchone():
+            raise CliError(f"unknown decision {args.decision!r}; `ledger status` and .ledger/ledger.db hold the ids")
+        con.execute("INSERT OR REPLACE INTO commits VALUES (?,?,?,'manual')", (sha, args.decision, ts))
+        con.commit()
+    print(f"{sha[:12]} -> {args.decision}")
+
+
+def fix_pattern(style, regex=None):
+    import re
+    from .label import FIX_STYLES
+    if not regex:
+        return FIX_STYLES[style]
+    try:
+        return re.compile(regex, re.I)
+    except re.error as e:
+        raise CliError(f"--fix-regex is not a valid regular expression: {e}") from None
+
+
+def cmd_import(args):
+    from .incidents import import_deploys, import_incidents
+    need_ledger(args.repo)
+    if not Path(args.file).is_file():
+        raise CliError(f"file not found: {args.file}")
+    with closing(connect(db_path(args.repo))) as con:
+        if args.kind == "incidents":
+            n = import_incidents(con, args.file)
+        else:
+            n = import_deploys(con, args.file)
+    print(f"imported {n} {args.kind}; run `ledger label` to link them to decisions")
+
+
+def cmd_sync(args):
+    from .pagerduty import PagerDutyError
+    from .pagerduty import sync as pd_sync
+    from .sentry import SentryError
+    from .sentry import sync as sentry_sync
+    need_ledger(args.repo)
+    try:
+        with closing(connect(db_path(args.repo))) as con:
+            if args.source == "sentry":
+                if not args.org:
+                    raise CliError("--org is required for sentry (the slug in your sentry.io address)")
+                result = sentry_sync(con, args.org, args.days, args.query,
+                                     levels=tuple(args.levels.split(",")) if args.levels else ())
+            else:
+                result = pd_sync(con, args.days, tuple(u for u in args.urgencies.split(",") if u))
+    except (SentryError, PagerDutyError) as e:
+        raise CliError(str(e)) from None
+    print(f"fetched {result['fetched']} issues, imported {result['imported']} as incidents. "
+          f"{args.source.title()} gives no suspect commits, so link them with an export or --incident-linking.")
+
+
+def cmd_status(args):
+    from .status import status
+    need_ledger(args.repo)
+    with closing(connect(db_path(args.repo))) as con:
+        r = status(con)
+    print(f"{r['decisions']} decisions, {r['attributed']} with commits, {r['mature']} with a closed "
+          f"window; {r['incidents']} incidents, {r['deploys']} deploys")
+    for arm, a in r["arms"].items():
+        print(f"  {arm:<16}{a['decisions']:>6} decisions (lowest chance {a['lowest_propensity'] * 100:.1f}%)")
+    active = active_decisions(args.repo)
+    if active:
+        print("\nactive now (commits on these branches are being tagged):")
+        for branch, decision_id in active:
+            print(f"  {branch:<28}{decision_id}")
+    print()
+    for note in r["notes"] or ["Nothing needs attention."]:
+        print(f"- {note}")
+
+
+def active_decisions(repo):
+    """[(branch, decision id)] for every branch with an active decision."""
+    folder = active_dir(repo)
+    found = []
+    for f in sorted(folder.glob("*")) if folder.exists() else []:
+        lines = f.read_text(encoding="utf-8", errors="replace").splitlines()
+        if lines:
+            found.append((lines[1] if len(lines) > 1 else "?", lines[0]))
+    return sorted(found)
+
+
+def cmd_plan(args):
+    from .plan import plan
+    try:
+        grid = [int(x) for x in args.grid.split(",")] if args.grid else None
+    except ValueError:
+        raise CliError("--grid must be whole numbers separated by commas, e.g. --grid 500,1000,2000") from None
+    r = plan(args.base_rate, args.effect, args.arms, args.epsilon, args.prefer, grid, args.reps, args.seed, args.power)
+    print(f"Detecting {r['effect'] * 100:+.1f}pp from a {r['base_rate'] * 100:.0f}% base rate, {r['arms']} arms, "
+          f"epsilon {r['epsilon']}, {r['reps']} simulations per row\n")
+    print(f"{'decisions':>10}{'power (one look)':>20}{'power (checked repeatedly)':>30}")
+    for row in r["table"]:
+        print(f"{row['n']:>10}{row['power_fixed']:>20.2f}{row['power_anytime']:>30.2f}")
+    for label_, key in (("one look", "n_for_target_fixed"), ("checked repeatedly", "n_for_target_anytime")):
+        n = r[key]
+        print(f"\n{r['target'] * 100:.0f}% power, {label_}: " + (f"about {n} finished decisions" if n else "not reached in this grid"))
+
+
+def run_label(repo, horizon, as_of, rev="HEAD", ignore_file=None, fix_re=None, early_days=7,
+              incident_linking="off", max_blamed=DEFAULT_MAX_BLAMED):
+    ignore = []
+    if ignore_file:
+        path = Path(ignore_file) if Path(ignore_file).is_absolute() else Path(repo) / ignore_file
+        if path.exists():
+            ignore = [ln.split()[0] for ln in path.read_text().splitlines()
+                      if ln.strip() and not ln.startswith("#")]
+    with closing(connect(db_path(repo))) as con:
+        stats = label(repo, con, horizon, as_of, rev, ignore, fix_re or fix_pattern("conventional"), early_days,
+                      incident_linking, max_blamed)
+    write_json(ledger_dir(repo) / "label.json", stats)
+    return stats
+
+
+def run_estimate(repo, baseline=None, boot=500, clip=None, stratum="stratum", seed=0, cluster=None, planned_n=2000,
+                 folds=DEFAULT_FOLDS):
+    with closing(connect(db_path(repo))) as con:
+        rows = load_rows(con, stratum, cluster)
+        if not rows:
+            raise CliError("no finished decisions to estimate from yet. Decisions count once their window has passed "
+                           "and `ledger label` has run; `ledger status` shows what is missing")
+        result = estimate(rows, baseline=baseline, boot=boot, clip=clip, seed=seed, planned_n=planned_n, folds=folds)
+        result["merge_balance"] = merge_balance(con)
+        result["early"] = early_readout(con, result["baseline"], stratum, cluster, planned_n)
+    write_json(ledger_dir(repo) / "estimate.json", result)
+    return result
+
+
+def run_report(repo, out=None, primary="dr", title="Consequence Ledger"):
+    d = ledger_dir(repo)
+    for name in ("estimate.json", "label.json"):
+        if not (d / name).exists():
+            raise CliError(f"nothing to report yet: run `ledger label` and `ledger estimate` first (missing {name})")
+    est = json.loads((d / "estimate.json").read_text())
+    stats = json.loads((d / "label.json").read_text())
+    truth = json.loads((d / "truth.json").read_text()) if (d / "truth.json").exists() else None
+    validation = json.loads((d / "validation.json").read_text()) if (d / "validation.json").exists() else None
+    out = Path(out or d / "report.html")
+    out.write_text(report_mod.render(est, stats, title, primary, truth, {"repo": Path(repo).name},
+                                     validation), encoding="utf-8")
+    return out
+
+
+def print_estimate(result, primary="dr"):
+    print(f"\n{'arm':<12}{'n':>6}{'naive':>9}{'ipw':>9}{'snipw':>9}{primary:>9}   95% CI          vs {result['baseline']}")
+    for arm, e in result["arms"].items():
+        est = e["estimates"]
+        vs = e["vs_baseline"][primary]
+        if result["diagnostics"][arm]["n"] == 0:
+            print(f"{arm:<12}{0:>6}  never chosen: no estimate")
+            continue
+        diff = "" if arm == result["baseline"] else f"{vs['value'] * 100:+.1f}pp [{vs['lo'] * 100:+.1f}, {vs['hi'] * 100:+.1f}]"
+        print(f"{arm:<12}{result['diagnostics'][arm]['n']:>6}"
+              + "".join(f"{est[k]['value'] * 100:>8.1f}%" for k in ("naive", "ipw", "snipw", primary))
+              + f"   [{est[primary]['lo'] * 100:4.1f}, {est[primary]['hi'] * 100:4.1f}]   {diff}")
+    early = result.get("early")
+    if early:
+        print(f"\nearly readout ({early['n']} decisions past the early window), dr vs {early['baseline']}: "
+              + ", ".join(f"{a} {v['diff'] * 100:+.1f}pp [{v['diff_lo'] * 100:+.1f}, {v['diff_hi'] * 100:+.1f}]"
+                          for a, v in early["arms"].items() if a != early["baseline"]))
+        cal = early.get("calibration")
+        if cal:
+            print(f"  on {cal['n']} decisions with both windows closed, {cal['surfaced_early'] * 100:.0f}% of final bad "
+                  "outcomes had surfaced early; early vs final there: "
+                  + ", ".join(f"{a} {v['early_diff'] * 100:+.1f} vs {v['final_diff'] * 100:+.1f}pp" for a, v in cal["pairs"].items()))
+    cs = [(a, v["dr"]) for a, v in result.get("analytic", {}).items() if a != result["baseline"]]
+    if cs:
+        print("\nanytime-valid (safe if you check repeatedly), dr vs " + result["baseline"] + ": "
+              + ", ".join(f"{a} [{d['cs_lo'] * 100:+.1f}, {d['cs_hi'] * 100:+.1f}]pp" for a, d in cs))
+
+
+def segment_rows(args):
+    """Finished decisions with the arms and baseline to compare, and the folds to use."""
+    need_ledger(args.repo)
+    with closing(connect(db_path(args.repo))) as con:
+        rows = load_rows(con, args.stratum, args.cluster)
+    if not rows:
+        raise CliError("no finished decisions yet. Decisions count once their window has passed and "
+                       "`ledger label` has run; `ledger status` shows what is missing")
+    arms = sorted({r["arm"] for r in rows} | {a for r in rows for a in r["p"]})
+    baseline = args.baseline or arms[0]
+    if baseline not in arms:
+        raise CliError(f"baseline {baseline!r} is not one of {arms}")
+    folds = args.folds if len(rows) >= MIN_CROSSFIT else 0
+    return rows, arms, baseline, folds
+
+
+def cmd_breakdown(args):
+    rows, arms, baseline, folds = segment_rows(args)
+    result = {"baseline": baseline, "stratum": args.stratum, "n": len(rows),
+              "arms": breakdown(rows, arms, baseline, args.clip, folds)}
+    write_json(ledger_dir(args.repo) / "breakdown.json", result)
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+    if not result["arms"]:
+        print("not enough data per stratum to compare anything yet")
+        return
+    for arm, d in result["arms"].items():
+        print(f"\n{arm} vs {baseline}, by '{args.stratum}'  (overall {d['overall'] * 100:+.1f}pp, "
+              f"spread between strata {d['tau'] * 100:.1f}pp)")
+        print(f"{'stratum':<22}{'n':>6}{'raw effect':>14}{'shrunk':>9}   shrunk 95% CI      adj. p")
+        for x in sorted(d["strata"], key=lambda x: x["shrunk"]):
+            print(f"{x['stratum']:<22}{x['n']:>6}{x['effect'] * 100:>+13.1f}p{x['shrunk'] * 100:>+8.1f}p"
+                  f"   [{x['shrunk_lo'] * 100:+5.1f}, {x['shrunk_hi'] * 100:+5.1f}]   {x['p_adjusted']:.3f}")
+        verdict = ("at least one stratum differs from the rest after adjusting for looking at all of them"
+                   if d["heterogeneous"] else "no stratum stands out once you account for how many were examined")
+        print(f"-> {verdict}.")
+
+
+def cmd_recommend(args):
+    rows, arms, baseline, folds = segment_rows(args)
+    try:
+        result = recommend(rows, arms, baseline, args.clip, folds)
+    except ValueError as exc:
+        raise CliError(str(exc))
+    result.update(baseline=baseline, stratum=args.stratum)
+    write_json(ledger_dir(args.repo) / "recommend.json", result)
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+    pp = lambda v: f"{v * 100:+.2f}pp"
+    print(f"\nwhat happened: {result['current_rate'] * 100:.1f}% of {len(rows)} decisions went bad")
+    print(f"routing each '{args.stratum}' to its best tool (chosen on one half, judged on the other):")
+    print(f"  {pp(result['gain'])} fewer bad outcomes  [{pp(result['gain_lo'])}, {pp(result['gain_hi'])}]")
+    print(f"always using the single best tool: {pp(result['best_single_gain'])}  "
+          f"[{pp(result['best_single_lo'])}, {pp(result['best_single_hi'])}]")
+    if result["stable_policy"]:
+        print("choices that did not change between halves: "
+              + ", ".join(f"{s} -> {a}" for s, a in sorted(result["stable_policy"].items())))
+    if result["unstable_strata"]:
+        print("changed with the data (no real preference): " + ", ".join(result["unstable_strata"]))
+    if result["worth_it"]:
+        print("-> the interval is above zero. Shift `--scores` toward these choices, and keep epsilon at 0.2 or more "
+              "so the next estimate stays valid.")
+    elif result["best_single_lo"] > 0:
+        print("-> any gain comes from one tool being better overall, not from matching tools to task types. "
+              "`ledger estimate` shows which.")
+    else:
+        print("-> the interval includes zero: no evidence yet that routing by task type beats what you did. "
+              "Keep randomizing.")
+
+
+def cmd_label(args):
+    need_ledger(args.repo)
+    print(json.dumps(run_label(args.repo, args.horizon, parse_date(args.as_of), args.rev, args.ignore_revs,
+                               fix_pattern(args.fix_style, args.fix_regex), args.early_days,
+                               args.incident_linking, args.max_blamed), indent=2))
+
+
+def cmd_estimate(args):
+    need_ledger(args.repo)
+    result = run_estimate(args.repo, args.baseline, args.boot, args.clip, args.stratum, cluster=args.cluster,
+                          planned_n=args.planned_n, folds=args.folds)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print_estimate(result, args.primary)
+
+
+def cmd_report(args):
+    need_ledger(args.repo)
+    print(run_report(args.repo, args.out, args.primary))
+
+
+def cmd_audit(args):
+    from .audit import audit, compile_rules
+    ignore = []
+    path = Path(args.repo) / args.ignore_revs
+    if path.exists():
+        ignore = [ln.split()[0] for ln in path.read_text().splitlines() if ln.strip() and not ln.startswith("#")]
+    result = audit(args.repo, args.horizon, parse_date(args.as_of), parse_date(args.since), args.rev,
+                   compile_rules(args.rule), ignore, fix_pattern(args.fix_style, args.fix_regex), args.max_blamed)
+    if args.json:
+        Path(args.json).write_text(json.dumps(result, indent=2))
+    if args.html:
+        Path(args.html).write_text(report_mod.render_audit(result, Path(args.repo).resolve().name), encoding="utf-8")
+    diffuse = result.get("fixes_too_diffuse", 0)
+    print(f"{result['mature_commits']} mature commits of {result['commits_scanned']}, {result['fix_commits']} fix commits"
+          + (f" ({diffuse} ignored as too diffuse)" if diffuse else "")
+          + f" (window {result['horizon_days']} days). Correlational: tools are used on different work.\n")
+    if not result["tools"]:
+        print(f"Nothing to report: no commit is old enough for its {result['horizon_days']}-day window to have closed "
+              "(or the history is empty after --since). Try a shorter --horizon, or come back later.")
+        return
+    print(f"{'tool':<14}{'commits':>8}{'reverted':>10}{'fixed':>7}{'bad rate':>10}   95% CI         size-adjusted")
+    for tool, t in result["tools"].items():
+        print(f"{tool:<14}{t['commits']:>8}{t['reverted']:>10}{t['fixed']:>7}{t['bad_rate'] * 100:>9.1f}%"
+              f"   [{t['ci_lo'] * 100:4.1f}, {t['ci_hi'] * 100:4.1f}]   {t['size_adjusted_rate'] * 100:5.1f}%")
+    for note in result.get("detection_notes", ()):
+        print(f"\nnote: {note}")
+
+
+def cmd_demo(args):
+    from .demo import build, validate
+    out = Path(args.out or Path(tempfile.gettempdir()) / "consequence-ledger-demo")
+    print(f"building synthetic repo in {out} ...")
+    repo, as_of, truth = build(out, n=args.n, seed=args.seed, horizon_days=args.horizon)
+    stats = run_label(repo, args.horizon, as_of)
+    print(json.dumps(stats, indent=2))
+    result = run_estimate(repo, boot=args.boot, seed=args.seed)
+    print_estimate(result)
+    print("\ntrue rates: " + ", ".join(f"{a} {v * 100:.1f}%" for a, v in truth.items()))
+    v = validate(repo, boot=args.boot, seed=args.seed)
+    print(f"labeler vs oracle: precision {v['precision']:.2f}, recall {v['recall']:.2f} "
+          f"(tp {v['tp']}, fp {v['fp']}, fn {v['fn']})")
+    print("DR on oracle labels: " + ", ".join(f"{a} {e['value'] * 100:.1f}%" for a, e in v["oracle_dr"].items()))
+    print(f"\nreport: {run_report(repo, title='Consequence Ledger demo')}")
+
+
+def add_fix_args(parser):
+    parser.add_argument("--fix-style", default="conventional", choices=["conventional", "keywords"],
+                        help="conventional: fix:/hotfix: prefixes; keywords: 'Fix crash...' style messages")
+    parser.add_argument("--fix-regex", help="custom regex on the commit subject (overrides --fix-style)")
+    parser.add_argument("--max-blamed", type=int, default=DEFAULT_MAX_BLAMED,
+                        help="ignore a fix that blames more than this many commits as too diffuse to attribute "
+                             f"(default {DEFAULT_MAX_BLAMED}; 0 keeps every fix)")
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(prog="ledger", description="Consequence Ledger: causal outcomes of AI coding decisions")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("init", help="create the ledger and install the commit hook")
+    s.add_argument("--repo", default=".")
+    s.set_defaults(fn=cmd_init)
+
+    s = sub.add_parser("decide", help="randomly choose an arm and log its propensity")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--arms", required=True, help="comma-separated, e.g. claude-code,codex,cursor")
+    s.add_argument("--scores", help="comma-separated preference scores (default: uniform)")
+    s.add_argument("--context", default="{}", help='JSON, e.g. {"stratum": "hard"}')
+    s.add_argument("--epsilon", type=float, default=0.1)
+    s.add_argument("--temperature", type=float, default=1.0)
+    s.add_argument("--policy-version", default="v1")
+    s.set_defaults(fn=cmd_decide)
+
+    s = sub.add_parser("done", help="stop tagging commits on the current branch with its decision")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--all", action="store_true", help="clear the active decision on every branch")
+    s.set_defaults(fn=cmd_done)
+
+    s = sub.add_parser("attach", help="map a commit (e.g. a squash merge) to a decision by hand")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--decision", required=True)
+    s.add_argument("--commit", required=True)
+    s.set_defaults(fn=cmd_attach)
+
+    s = sub.add_parser("sync", help="pull incidents live (reads SENTRY_AUTH_TOKEN or PAGERDUTY_API_KEY from the environment)")
+    s.add_argument("source", choices=["sentry", "pagerduty"])
+    s.add_argument("--org", help="Sentry organization slug (sentry only)")
+    s.add_argument("--days", type=int, default=90)
+    s.add_argument("--query", default="", help="Sentry issue search, e.g. 'is:unresolved environment:production'")
+    s.add_argument("--levels", default="error,fatal", help="Sentry issue levels to count; empty for all")
+    s.add_argument("--urgencies", default="high", help="PagerDuty urgencies to count, comma-separated; empty for all")
+    s.add_argument("--repo", default=".")
+    s.set_defaults(fn=cmd_sync)
+
+    s = sub.add_parser("status", help="check the ledger for gaps before you trust an estimate")
+    s.add_argument("--repo", default=".")
+    s.set_defaults(fn=cmd_status)
+
+    s = sub.add_parser("plan", help="how many finished decisions you need to detect a difference")
+    s.add_argument("--base-rate", type=float, required=True, help="expected bad-outcome rate of the baseline, e.g. 0.12")
+    s.add_argument("--effect", type=float, required=True, help="difference to detect, e.g. -0.03 for 3 points better")
+    s.add_argument("--arms", type=int, default=2)
+    s.add_argument("--epsilon", type=float, default=0.1)
+    s.add_argument("--prefer", type=float, default=0.0, help="score gap in favour of the tested arm in your routing")
+    s.add_argument("--power", type=float, default=0.8)
+    s.add_argument("--grid", help="comma-separated decision counts, default 500..16000")
+    s.add_argument("--reps", type=int, default=200)
+    s.add_argument("--seed", type=int, default=0)
+    s.set_defaults(fn=cmd_plan)
+
+    s = sub.add_parser("label", help="detect reverts and fixes and label each decision")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--horizon", type=int, default=30, help="days")
+    s.add_argument("--as-of", help="ISO date or unix seconds (default: now)")
+    s.add_argument("--rev", default="HEAD")
+    s.add_argument("--ignore-revs", default=".git-blame-ignore-revs", help="commits SZZ should skip")
+    s.add_argument("--early-days", type=int, default=7, help="early-warning window for a first readout (0 = off)")
+    s.add_argument("--incident-linking", default="off", choices=["off", "latest", "window"],
+                   help="for incidents without suspect commits: off (default, safest), latest deploy, or every "
+                        "matching commit in the window")
+    add_fix_args(s)
+    s.set_defaults(fn=cmd_label)
+
+    s = sub.add_parser("import", help="import incidents or deploys exported from Sentry, PagerDuty, etc.")
+    s.add_argument("kind", choices=["incidents", "deploys"])
+    s.add_argument("--file", required=True, help="CSV or JSON export")
+    s.add_argument("--repo", default=".")
+    s.set_defaults(fn=cmd_import)
+
+    s = sub.add_parser("estimate", help="causal estimates per arm")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--baseline")
+    s.add_argument("--boot", type=int, default=500)
+    s.add_argument("--clip", type=float, help="cap on importance weights")
+    s.add_argument("--stratum", default="stratum", help="context key used by the outcome model")
+    s.add_argument("--cluster", help="context key whose values share outcomes, e.g. developer or service")
+    s.add_argument("--planned-n", type=int, default=2000,
+                   help="decisions you expect at the final readout; tunes the anytime-valid interval (fix it up front)")
+    s.add_argument("--primary", default="dr", choices=["ipw", "snipw", "dm", "dr"])
+    s.add_argument("--folds", type=int, default=DEFAULT_FOLDS,
+                   help="cross-fitting folds for the outcome model (0 fits it on all decisions)")
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_estimate)
+
+    s = sub.add_parser("breakdown", help="which tool is better for which kind of task (shrunk, multiplicity-aware)")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--baseline")
+    s.add_argument("--clip", type=float, help="cap on importance weights")
+    s.add_argument("--stratum", default="stratum", help="context key (or comma-separated keys) to break down by")
+    s.add_argument("--cluster", help="context key whose values share outcomes")
+    s.add_argument("--folds", type=int, default=DEFAULT_FOLDS)
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_breakdown)
+
+    s = sub.add_parser("recommend", help="what routing each kind of task to its best tool would be worth (honestly)")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--baseline")
+    s.add_argument("--clip", type=float, help="cap on importance weights")
+    s.add_argument("--stratum", default="stratum", help="context key (or comma-separated keys) to route by")
+    s.add_argument("--cluster", help="context key whose values share outcomes")
+    s.add_argument("--folds", type=int, default=DEFAULT_FOLDS)
+    s.add_argument("--json", action="store_true")
+    s.set_defaults(fn=cmd_recommend)
+
+    s = sub.add_parser("report", help="write the HTML report")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--out")
+    s.add_argument("--primary", default="dr", choices=["ipw", "snipw", "dm", "dr"])
+    s.set_defaults(fn=cmd_report)
+
+    s = sub.add_parser("audit", help="baseline revert/fix rates per AI tool from history (correlational)")
+    s.add_argument("--repo", default=".")
+    s.add_argument("--horizon", type=int, default=30, help="days")
+    s.add_argument("--as-of", help="ISO date or unix seconds (default: now)")
+    s.add_argument("--since", help="only commits after this date")
+    s.add_argument("--rev", default="HEAD")
+    s.add_argument("--rule", action="append", default=[], help="extra tool=regex on the commit message")
+    s.add_argument("--ignore-revs", default=".git-blame-ignore-revs")
+    s.add_argument("--json", help="write full results here")
+    s.add_argument("--html", help="write an HTML summary here")
+    add_fix_args(s)
+    s.set_defaults(fn=cmd_audit)
+
+    s = sub.add_parser("demo", help="synthetic end-to-end run with known true effects")
+    s.add_argument("--out")
+    s.add_argument("--n", type=int, default=2400)
+    s.add_argument("--seed", type=int, default=7)
+    s.add_argument("--horizon", type=int, default=30)
+    s.add_argument("--boot", type=int, default=300)
+    s.set_defaults(fn=cmd_demo)
+
+    args = p.parse_args(argv)
+    try:
+        if getattr(args, "repo", None) is not None and args.cmd not in ("demo", "plan"):
+            # Work from the repository's main working tree whatever folder or worktree we were run in,
+            # but remember where we were: its checked-out branch decides which decision applies.
+            args.workdir = args.repo
+            args.repo = str(repo_root(args.repo))
+        args.fn(args)
+    except CliError as e:
+        sys.exit(f"error: {e}")
+    except GitError as e:
+        sys.exit(f"error: {friendly_git_error(e, getattr(args, 'repo', '.'))}")
+    except (ValueError, OSError) as e:
+        # ValueError covers invalid options deep in the library (epsilon, horizon, base rate ...);
+        # OSError covers missing files, permissions, and the demo refusing to overwrite a folder.
+        sys.exit(f"error: {e}")
+    except KeyboardInterrupt:
+        sys.exit(130)