rung-cli 0.1.2__py3-none-any.whl

rung/cli/__init__.py

@@ -0,0 +1,157 @@
+"""`rung` command line: argument parsing and error handling. Commands live in `commands`."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from rung import __version__
+from rung.checks.presets import PRESETS
+from rung.cli import commands as c
+from rung.cli.output import Output
+from rung.core.config import CHECK_KINDS, ConfigError
+from rung.core.errors import RungError, ToolMissing
+from rung.core.git import GitError
+from rung.drafting import providers
+from rung.engines.sarif import LEVELS
+
+EXIT_USAGE, EXIT_TOOL, EXIT_GIT = 2, 3, 4
+
+DESCRIPTION = """\
+Rung keeps a ledger of what has actually been verified in a codebase, and against
+which exact code. Checks range from your test suite and security scanners to TLA+
+model checking and Lean proofs; laws in LAWS.md say what must never break.
+
+exit codes: 0 ok · 1 a check or gate failed · 2 configuration or usage error ·
+3 a required tool is missing · 4 git error"""
+
+
+def _common_options(*, defaults: bool) -> argparse.ArgumentParser:
+    """Options accepted before or after the subcommand.
+
+    The subcommand copies use SUPPRESS defaults so `rung -C dir check` is not
+    overwritten by the subcommand's own default.
+    """
+    parser = argparse.ArgumentParser(add_help=False)
+    suppress = not defaults
+    parser.add_argument("-C", "--dir", help="project directory (default: current)",
+                        default=argparse.SUPPRESS if suppress else ".")  # fmt: skip
+    parser.add_argument("--json", action="store_true", help="print machine-readable JSON",
+                        default=argparse.SUPPRESS if suppress else False)  # fmt: skip
+    parser.add_argument("--no-color", action="store_true", help="disable colour",
+                        default=argparse.SUPPRESS if suppress else False)  # fmt: skip
+    return parser
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = _common_options(defaults=False)
+    p = argparse.ArgumentParser(
+        prog="rung",
+        description=DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        parents=[_common_options(defaults=True)],
+    )
+    p.add_argument("--version", action="version", version=f"rung {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    def add(name: str, func, help_text: str) -> argparse.ArgumentParser:
+        s = sub.add_parser(name, help=help_text, description=help_text, parents=[common])
+        s.set_defaults(func=func)
+        return s
+
+    s = add("init", c.cmd_init, "survey the repo, choose a model provider, write rung.toml")
+    s.add_argument("--provider", choices=list(providers.PROVIDERS))
+    s.add_argument("--model", help="model for drafting, passed to the provider (e.g. sonnet, opus, gpt-6.1-sol); "
+                   "empty uses the CLI's own default")  # fmt: skip
+    add("plan", c.cmd_plan, "recommend checks for this repo")
+    add("doctor", c.cmd_doctor, "show which checkers, scanners and model CLIs are available")
+    s = add("agents", c.cmd_agents, "install the agent skill and AGENTS.md rules (and enforcement hooks)")
+    s.add_argument("--hooks", action="store_true", help="also install a Claude Code Stop hook that blocks stale work")
+    s = add("hook", c.cmd_hook, "entry point for agent hooks (reads the hook payload on stdin)")
+    s.add_argument("event", choices=["stop"])
+
+    s = add("check", c.cmd_check, "run checks and record verdicts")
+    s.add_argument("ids", nargs="*", help="check ids (default: all)")
+    s.add_argument("--changed", action="store_true", help="only checks touched by this branch's changes")
+    s.add_argument("--base", help="branch to compare with (default: the repository's default branch)")
+    s.add_argument("--ci", action="store_true", help="skip checks that are already fresh")
+    s = add("status", c.cmd_status, "show which verdicts are fresh, stale or failing")
+    s.add_argument("--ci", action="store_true", help="exit 1 unless every verdict is fresh")
+    s = add("report", c.cmd_report, "summarize checks, laws, new findings and fix proofs")
+    s.add_argument("--format", choices=["md", "json"], default="md")
+    s = add("prove", c.cmd_prove, "show a new test fails without the fix and passes with it")
+    s.add_argument("test_command", metavar="command", help="test command, e.g. 'pytest tests/test_refunds.py'")
+    s.add_argument("--base", help="branch without the fix (default: the repository's default branch)")
+    s.add_argument("--tests", nargs="*", help="test files to carry over (default: test files changed on this branch)")
+    s.add_argument("--expect", help="text the failing run must contain, e.g. the assertion")
+    s.add_argument("--cwd", default=".", help="directory to run the test command in (e.g. backend)")
+    s = add("ledger", c.cmd_ledger, "check the verdict files for corruption")
+    s.add_argument("--prune", action="store_true", help="remove verdicts of checks no longer in rung.toml")
+
+    s = add("laws", c.cmd_laws, "list laws and whether each one holds")
+    s.add_argument("--approve", metavar="LAW_ID", help="mark a proposed law as approved")
+    s = add("add", c.cmd_add, "declare a check in rung.toml")
+    s.add_argument("kind", choices=[k for k in CHECK_KINDS if k not in ("tla", "lean", "drt")])
+    s.add_argument("id")
+    s.add_argument("--run", help="command to run (command, custom scan; for evidence, omit it to attest instead)")
+    s.add_argument("--cwd", help="directory to run the command in, relative to the project root")
+    s.add_argument("--tool", choices=list(PRESETS), help="scanner preset (scan)")
+    s.add_argument("--fail-on", choices=LEVELS, help="lowest SARIF level that blocks (scan)")
+    s.add_argument("--require", nargs="*", help="artifact suffixes the evidence must include, e.g. .webm")
+    s.add_argument("--min-age-days", type=int, default=30, help="youngest acceptable new package (deps)")
+    s.add_argument("--covers", nargs="*", help="files whose change stales the verdict (globs)")
+    s = add("attest", c.cmd_attest, "record evidence an agent or person captured (evidence checks without `run`)")
+    s.add_argument("check")
+    s.add_argument("files", nargs="+", help="recordings, screenshots, transcripts")
+    s.add_argument("--by", required=True, help="who or what recorded it, e.g. claude-in-chrome, computer-use, codex")
+    s.add_argument("--note", help="what was driven and what was seen")
+    s = add("baseline", c.cmd_baseline, "accept a scan check's existing findings; only new ones will block")
+    s.add_argument("check")
+    s = add("waive", c.cmd_waive, "accept one finding, with a reason and an expiry")
+    s.add_argument("check")
+    s.add_argument("fingerprint")
+    s.add_argument("--reason", required=True)
+    s.add_argument("--days", type=int, default=30, help="days until the waiver expires (default 30)")
+    s.add_argument("--until", help="expiry date, YYYY-MM-DD")
+    s.add_argument("--approved-by", help="who accepts the risk (default: git user.name)")
+    s = add("draft", c.cmd_draft, "draft a TLA+ spec, Lean model, property tests or drive script; a checker decides")
+    s.add_argument("kind", choices=["tla", "lean", "property", "runtime"])
+    s.add_argument("files", nargs="*", help="source files to model (tla, lean) or to focus on (runtime)")
+    s.add_argument("--intent", help="what the code must guarantee, or (runtime) which feature to drive")
+    s.add_argument("--require", nargs="*", help="(runtime) evidence the script must leave, e.g. .webm for a video")
+    s.add_argument("--id")
+    s.add_argument("--out", help="where to write the result: a directory (tla, lean) or a test file (property)")
+    s.add_argument("--model", help="model for this draft only (default: [llm] model in rung.toml, else the CLI's)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    out = Output(json_mode=args.json, color=False if args.no_color else None)
+    try:
+        return args.func(args, out)
+    except ConfigError as exc:
+        out.error(str(exc))
+        return EXIT_USAGE
+    except ToolMissing as exc:
+        out.error(str(exc))
+        return EXIT_TOOL
+    except GitError as exc:
+        out.error(str(exc))
+        return EXIT_GIT
+    except RungError as exc:
+        out.error(str(exc))
+        return c.GATE_FAILED
+    except KeyboardInterrupt:
+        out.error("interrupted")
+        return 130
+    except Exception as exc:  # a bug or an unexpected input: say so briefly, not with a traceback
+        if os.environ.get("RUNG_DEBUG"):
+            raise
+        out.error(f"unexpected error: {type(exc).__name__}: {exc} (set RUNG_DEBUG=1 for the traceback)")
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

rung/cli/commands/__init__.py

@@ -0,0 +1,13 @@
+"""Command implementations. Each takes parsed args and an Output, and returns an exit code."""
+
+from rung.cli.commands.common import GATE_FAILED, OK
+from rung.cli.commands.draft import cmd_draft
+from rung.cli.commands.manage import cmd_add, cmd_attest, cmd_baseline, cmd_laws, cmd_waive
+from rung.cli.commands.run import cmd_check, cmd_ledger, cmd_prove, cmd_report, cmd_status
+from rung.cli.commands.setup import cmd_agents, cmd_doctor, cmd_hook, cmd_init, cmd_plan
+
+__all__ = [
+    "GATE_FAILED", "OK", "cmd_add", "cmd_agents", "cmd_attest", "cmd_baseline", "cmd_check", "cmd_doctor", "cmd_draft",
+    "cmd_hook", "cmd_init", "cmd_laws", "cmd_ledger", "cmd_plan", "cmd_prove", "cmd_report", "cmd_status",
+    "cmd_waive",
+]  # fmt: skip

rung/cli/commands/common.py

@@ -0,0 +1,41 @@
+"""Helpers shared by the command modules."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from rung.checks import registry
+from rung.cli.output import Output
+from rung.core import git
+from rung.core.config import CONFIG_NAME, Check, Config, find_root, load, save
+
+OK, GATE_FAILED = 0, 1
+OK, GATE_FAILED = 0, 1
+
+
+def load_config(args) -> Config:
+    return load(find_root(Path(args.dir)))
+
+
+def ask(question: str, default: str = "") -> str:
+    if not sys.stdin.isatty():
+        return default
+    suffix = f" [{default}]" if default else ""
+    print(f"{question}{suffix}: ", end="", file=sys.stderr, flush=True)
+    return input().strip() or default
+
+
+def resolve_base(root: Path, base: str | None) -> str:
+    """A merge base commit for `base` (or the default branch)."""
+    return git.merge_base(root, base or git.default_base(root))
+
+
+def add_check(config: Config, check: Check, out: Output) -> None:
+    registry.get(check.kind)  # validate the kind before writing anything
+    replaced = any(c.id == check.id for c in config.checks)
+    config.checks = [c for c in config.checks if c.id != check.id] + [check]
+    save(config)
+    out.emit({"check": check.id, "kind": check.kind, "covers": check.covers, "options": check.options,
+              "replaced": replaced})  # fmt: skip
+    out.line(f"{'Updated' if replaced else 'Added'} check {check.id!r} ({check.kind}) in {CONFIG_NAME}.")

rung/cli/commands/draft.py

@@ -0,0 +1,214 @@
+"""`rung draft`: model-drafted TLA+ specs, Lean models and runtime drive scripts."""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from dataclasses import replace
+from pathlib import Path
+
+from rung import agents
+from rung.analysis import survey
+from rung.cli.commands.common import GATE_FAILED, OK, add_check, load_config
+from rung.cli.output import Output
+from rung.core import laws
+from rung.core.config import Check, Config, ConfigError
+from rung.drafting import lean as lean_draft
+from rung.drafting import property as property_draft
+from rung.drafting import providers, runtime
+from rung.drafting import tla as tla_draft
+
+
+def drafted_by(cfg: Config, provider: providers.Provider | None = None) -> str:
+    """Which provider and model drafted an artifact, recorded on the check it creates.
+
+    After a draft, `provider` reports the models that actually answered (Claude Code's own report, or
+    Codex's configured default), so `default` is only left when the tool does not say.
+    """
+    model = provider.models() if provider else cfg.llm.model or "your CLI's default model"
+    return f"{cfg.llm.provider}:{model}"
+
+
+def _provider(cfg: Config, args) -> providers.Provider:
+    """The configured provider, with `--model` applied to this draft only (rung.toml is not changed)."""
+    return providers.get(replace(cfg.llm, model=args.model) if args.model else cfg.llm)
+
+
+def _slug(paths: list[str]) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", Path(paths[0]).stem.lower()).strip("-") or "spec"
+
+
+def _lean_exe(project: Path) -> str:
+    try:
+        lakefile = tomllib.loads((project / "lakefile.toml").read_text())
+    except (OSError, tomllib.TOMLDecodeError):
+        return ""
+    exes = lakefile.get("lean_exe", [])
+    return exes[0].get("name", "") if exes else ""
+
+
+def _draft_runtime(args, cfg: Config, out: Output) -> int:
+    provider = _provider(cfg, args)
+    info = survey.survey(cfg.root)
+    check_id = args.id or "runtime"
+    out.line(
+        f"Drafting a runtime verification script with {drafted_by(cfg, provider)}; Rung runs it until it proves itself."
+    )
+    result = runtime.draft_runtime(
+        provider,
+        cfg.root,
+        info,
+        focus=args.files,
+        check_id=check_id,
+        intent=args.intent or "",
+        require=tuple(args.require or ()),
+    )
+    out.emit({"ok": result.ok, "message": result.message, "rounds": result.rounds, "covers": result.covers,
+              "files": [str(f.relative_to(cfg.root)) for f in result.files], "evidence": result.evidence})  # fmt: skip
+    out.line(f"{'OK' if result.ok else 'FAILED'} after {result.rounds} round(s): {result.message}")
+    out.detail(f"drafted by {drafted_by(cfg, provider)}", indent=2)
+    if result.notes:
+        out.line("Notes from the model:")
+        out.detail(result.notes, indent=2)
+    for f in result.files:
+        out.detail(f"wrote {f.relative_to(cfg.root)}", indent=2)
+    for e in result.evidence:
+        out.detail(f"evidence {e}", indent=2)
+    if not result.ok:
+        out.line("The last script is kept for you to finish by hand; it is not registered as a check.")
+        return GATE_FAILED
+    add_check(
+        cfg,
+        Check(
+            check_id,
+            "evidence",
+            result.covers,
+            {
+                "run": result.run,
+                "timeout": 900,
+                "require": list(args.require or []),
+                "drafted_by": drafted_by(cfg, provider),
+            },
+        ),
+        out,
+    )
+    skill = agents.install_verify_skill(cfg.root, cfg.name, check_id)
+    out.line(f"wrote {skill.relative_to(cfg.root)} so agents verify user-facing changes with `rung check {check_id}`.")
+    return OK
+
+
+def _draft_property(args, cfg: Config, out: Output, sources: list[Path], rel: list[str]) -> int:
+    root = cfg.root
+    check_id = args.id or f"{_slug(rel)}-properties"
+    provider = _provider(cfg, args)
+    out.line(
+        f"Drafting property tests for {', '.join(rel)} with {drafted_by(cfg, provider)}; Rung runs them, then breaks "
+        "the code on purpose to see whether they notice ..."
+    )
+    result, target = property_draft.draft(
+        provider, root, sources, _slug(rel), intent=args.intent or "", out=args.out or ""
+    )
+    files = [f.relative_to(root).as_posix() for f in result.files]
+    out.emit({"ok": result.ok, "message": result.message, "rounds": result.rounds, "trace": result.trace,
+              "files": files, "warnings": result.warnings, "run": target.command})  # fmt: skip
+    out.line(f"{'OK' if result.ok else 'FAILED'} after {result.rounds} round(s): {result.message}")
+    out.detail(f"drafted by {drafted_by(cfg, provider)}", indent=2)
+    if result.notes:
+        out.line("Notes from the model:")
+        out.detail(result.notes, indent=2)
+    for f in files:
+        out.detail(f"wrote {f}", indent=2)
+    for w in result.warnings:
+        out.detail(w, indent=2)
+    if result.trace:
+        out.line("\nFailing example:")
+        out.detail(result.trace, indent=2)
+        out.line(
+            "\nIf this is a real bug, fix the code and run `rung check`. If the law is wrong, edit the test yourself."
+        )
+        return GATE_FAILED
+    if not result.ok:
+        return GATE_FAILED
+    # The verdict depends on the code under test, whatever it imports, and the runner's configuration:
+    # cover the whole project directory, and the test file itself.
+    covers = ["**/*"] if target.project == "." else [f"{target.project}/**"]
+    options = {"run": target.command, "drafted_by": drafted_by(cfg, provider), "specs": [target.test_file]}
+    if target.project != ".":
+        options["cwd"] = target.project
+    add_check(cfg, Check(check_id, "command", covers, options), out)
+    if added := laws.propose(root, result.laws, [check_id]):
+        out.line(f"Proposed {len(added)} law(s) in {laws.LAWS_FILE}: {', '.join(added)}.")
+        out.line("Read each one; approve with `rung laws --approve <id>` only if it says what you mean.")
+    return OK
+
+
+def cmd_draft(args, out: Output) -> int:
+    cfg = load_config(args)
+    if args.kind == "runtime":
+        return _draft_runtime(args, cfg, out)
+    if not args.files:
+        raise ConfigError(f"`rung draft {args.kind}` needs the source files to model")
+    provider = _provider(cfg, args)
+    root = cfg.root
+    sources = [(root / p).resolve() for p in args.files]
+    missing = [str(s) for s in sources if not s.is_file()]
+    if missing:
+        raise ConfigError(f"not found: {', '.join(missing)}")
+    rel = [s.relative_to(root).as_posix() for s in sources]
+    if args.kind == "property":
+        return _draft_property(args, cfg, out, sources, rel)
+    check_id = args.id or f"{_slug(rel)}-{args.kind}"
+    target = root / (args.out or f"spec/{args.kind}/{_slug(rel)}")
+    target.mkdir(parents=True, exist_ok=True)
+    out.line(f"Drafting {args.kind} for {', '.join(rel)} with {drafted_by(cfg, provider)} ...")
+
+    drafter = tla_draft.draft if args.kind == "tla" else lean_draft.draft
+    result = drafter(provider, root, sources, target, intent=args.intent or "")
+    out.emit({"ok": result.ok, "message": result.message, "rounds": result.rounds, "trace": result.trace,
+              "files": [str(f.relative_to(root)) for f in result.files]})  # fmt: skip
+    out.line(f"{'OK' if result.ok else 'FAILED'} after {result.rounds} round(s): {result.message}")
+    out.detail(f"drafted by {drafted_by(cfg, provider)}", indent=2)
+    if result.notes:
+        out.line("Notes from the model:")
+        out.detail(result.notes, indent=2)
+    for f in result.files:
+        out.detail(f"wrote {f.relative_to(root)}", indent=2)
+    if result.trace:
+        out.line("\nCounterexample:")
+        out.detail(result.trace, indent=2)
+        out.line("\nIf this is a real bug, fix the code and run `rung check`. If the spec is wrong, edit it yourself.")
+    if not result.ok:
+        return GATE_FAILED
+
+    if args.kind == "tla":
+        spec = next(f for f in result.files if f.suffix == ".tla")
+        cfg_file = next(f for f in result.files if f.suffix == ".cfg")
+        options = {"spec": spec.relative_to(root).as_posix(), "config": cfg_file.relative_to(root).as_posix(),
+                   "drafted_by": drafted_by(cfg, provider)}  # fmt: skip
+        add_check(cfg, Check(check_id, "tla", rel, options), out)
+    else:
+        project = target.relative_to(root).as_posix()
+        add_check(
+            cfg,
+            Check(
+                check_id,
+                "lean",
+                [],
+                {"project": project, "theorems": result.theorems, "drafted_by": drafted_by(cfg, provider)},
+            ),
+            out,
+        )
+        exe = _lean_exe(target)
+        if exe and result.alphabet and (target / "drt_adapter.py").exists():
+            options = {
+                "model": f"lake exe {exe}", "model_cwd": project,
+                "impl": f"python3 {project}/drt_adapter.py", "alphabet": result.alphabet,
+                "cases": 2000, "max_len": 8, "specs": [f"{project}/**/*.lean", f"{project}/drt_adapter.py"],
+            }  # fmt: skip
+            add_check(cfg, Check(f"{check_id}-drt", "drt", rel, options), out)
+    enforcing = [check_id] if args.kind == "tla" else [check_id, f"{check_id}-drt"]
+    added = laws.propose(root, result.laws, enforcing)
+    if added:
+        out.line(f"Proposed {len(added)} law(s) in {laws.LAWS_FILE}: {', '.join(added)}.")
+        out.line("Read each one; approve with `rung laws --approve <id>` only if it says what you mean.")
+    return OK

rung/cli/commands/manage.py

@@ -0,0 +1,112 @@
+"""Commands that change what is checked: laws, add, baseline, waive."""
+
+from __future__ import annotations
+
+import re
+from datetime import date, timedelta
+from pathlib import Path
+
+from rung.checks import findings, registry, runner
+from rung.checks.presets import PRESETS
+from rung.checks.scan import ScanChecker
+from rung.cli.commands.common import OK, add_check, load_config
+from rung.cli.output import STATE_STYLE, VERDICT_STYLE, Output
+from rung.core import git, laws
+from rung.core.config import Check, ConfigError
+
+
+def cmd_laws(args, out: Output) -> int:
+    cfg = load_config(args)
+    if args.approve:
+        try:
+            laws.set_status(cfg.root, args.approve, "approved")
+        except KeyError as exc:
+            raise ConfigError(f"no law {args.approve!r} in {laws.LAWS_FILE}") from exc
+        out.line(f"Approved {args.approve}.")
+    statuses = {s.check_id: s for s in runner.statuses(cfg)}
+    rows = [(law, *laws.state(law, statuses)) for law in laws.load(cfg.root)]
+    out.emit([{"id": law.id, "text": law.text, "state": st, "why": why, "enforced_by": law.enforced_by}
+              for law, st, why in rows])  # fmt: skip
+    if not rows:
+        out.line(f"No laws in {laws.LAWS_FILE} yet.")
+    for law, st, why in rows:
+        out.line(f"{out.badge(st, STATE_STYLE, 11)}{law.id}")
+        out.detail(law.text, indent=11)
+        out.detail(out.style(why, "dim"), indent=11)
+    return OK
+
+
+def cmd_add(args, out: Output) -> int:
+    cfg = load_config(args)
+    options: dict[str, object] = {}
+    if args.kind in ("command", "evidence"):
+        if not args.run and args.kind == "command":
+            raise ConfigError("`rung add command` needs --run")
+        if args.run:
+            options["run"] = args.run
+        if args.cwd:
+            options["cwd"] = args.cwd
+        if args.require:
+            options["require"] = args.require
+    elif args.kind == "scan":
+        if not (args.tool or args.run):
+            raise ConfigError(f"`rung add scan` needs --tool (one of {', '.join(PRESETS)}) or --run")
+        if args.tool:
+            options["tool"] = args.tool
+        if args.run:
+            options["run"] = args.run
+        if args.cwd:
+            options["cwd"] = args.cwd
+        if args.fail_on:
+            options["fail_on"] = args.fail_on
+    elif args.kind == "deps":
+        options["min_age_days"] = args.min_age_days
+    add_check(cfg, Check(args.id, args.kind, args.covers or [], options), out)
+    return OK
+
+
+def cmd_baseline(args, out: Output) -> int:
+    cfg = load_config(args)
+    check = cfg.check(args.check)
+    if check.kind not in ("scan", "shortcuts"):
+        raise ConfigError("baselines apply to `scan` and `shortcuts` checks")
+    checker = registry.get(check.kind)
+    assert isinstance(checker, ScanChecker)
+    found = checker.collect(cfg.root, check, check.get_int("timeout", 900))
+    path = findings.save_baseline(cfg.root, check.id, found, git.head(cfg.root))
+    out.emit({"check": check.id, "findings": len(found), "path": str(path.relative_to(cfg.root))})
+    out.line(f"Recorded {len(found)} existing finding(s) for {check.id!r} as accepted ({path.relative_to(cfg.root)}).")
+    out.line("Commit this file; from now on only findings beyond it will block.")
+    return OK
+
+
+def cmd_waive(args, out: Output) -> int:
+    cfg = load_config(args)
+    check = cfg.check(args.check)
+    if not re.fullmatch(r"[0-9a-f]{16}", args.fingerprint):
+        raise ConfigError("a fingerprint is the 16-character hex id shown in brackets by `rung check`")
+    try:
+        expires = date.fromisoformat(args.until) if args.until else date.today() + timedelta(days=args.days)
+    except ValueError as exc:
+        raise ConfigError(f"--until must be a date like 2026-12-31, not {args.until!r}") from exc
+    if expires < date.today():
+        raise ConfigError("a waiver must expire in the future")
+    approver = args.approved_by or git.user_name(cfg.root)
+    if not approver:
+        raise ConfigError("cannot tell who approves this waiver; pass --approved-by")
+    w = findings.Waiver(check.id, args.fingerprint, args.reason, approver, expires)
+    path = findings.add_waiver(cfg.root, w)
+    out.emit({"check": w.check, "fingerprint": w.fingerprint, "expires": str(w.expires), "approved_by": approver})
+    out.line(f"Waived {w.fingerprint} on {w.check!r} until {w.expires} ({path.relative_to(cfg.root)}).")
+    return OK
+
+
+def cmd_attest(args, out: Output) -> int:
+    cfg = load_config(args)
+    result = runner.attest(cfg, cfg.check(args.check), [Path(f) for f in args.files], by=args.by, note=args.note or "")
+    out.emit({"check": result.check.id, "verdict": result.verdict, "summary": result.outcome.summary,
+              "evidence": list(result.outcome.evidence)})  # fmt: skip
+    out.line(f"{out.badge('pass', VERDICT_STYLE, 10)} {result.check.id}: {result.outcome.summary}")
+    for line in result.outcome.lines:
+        out.detail(line, indent=11)
+    return OK

rung/cli/commands/run.py

@@ -0,0 +1,114 @@
+"""Commands that run and report checks: check, status, report, prove, ledger."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rung.analysis import report
+from rung.checks import prove, runner
+from rung.cli.commands.common import GATE_FAILED, OK, load_config, resolve_base
+from rung.cli.output import STATE_STYLE, VERDICT_STYLE, Output
+from rung.core import git, ledger
+from rung.core.config import CONFIG_NAME, find_root
+
+
+def _print_result(result: runner.Result, out: Output) -> None:
+    o = result.outcome
+    out.line(f"{out.badge(o.verdict, VERDICT_STYLE, 6)}{result.check.id} ({result.check.kind}): {o.summary}")
+    for line in o.lines:
+        out.detail(line)
+
+
+def cmd_check(args, out: Output) -> int:
+    cfg = load_config(args)
+    base: str | None = resolve_base(cfg.root, args.base) if args.changed or args.base else None
+    changed = git.changed_files(cfg.root, base) if args.changed and base else None
+    selected = runner.select(cfg, args.ids, changed)
+    if args.ci:
+        # Reuse a verdict only if it is fresh and was made against the same comparison base.
+        view = ledger.View(cfg.root)
+        selected = [c for c in selected if not runner.status(cfg, c, base=base or "", view=view).trusted]
+    if not cfg.checks:
+        out.error(f"no checks declared in {CONFIG_NAME}; see `rung plan` or `rung add`")
+        return GATE_FAILED
+    results = [runner.run_check(cfg, c, base=base) for c in selected]
+    out.emit({
+        "base": base,
+        "results": [{"id": r.check.id, "kind": r.check.kind, "verdict": r.verdict, "summary": r.outcome.summary,
+                     "lines": r.outcome.lines, "findings": r.outcome.findings} for r in results],
+    })  # fmt: skip
+    if not results:
+        out.line("Nothing to run: every selected check is fresh or untouched by this change.")
+    for r in results:
+        _print_result(r, out)
+    return GATE_FAILED if any(r.verdict != "pass" for r in results) else OK
+
+
+def cmd_status(args, out: Output) -> int:
+    cfg = load_config(args)
+    rows = runner.statuses(cfg)
+    problems = ledger.problems(cfg.root)
+    out.emit({
+        "checks": [{"id": s.check_id, "state": s.state, "at": (s.entry or {}).get("at"), "changed": s.changed}
+                   for s in rows],
+        "ledger_problems": problems,
+    })  # fmt: skip
+    for s in rows:
+        when = (s.entry or {}).get("at", "")
+        out.line(f"{out.badge(s.state, STATE_STYLE, 10)} {s.check_id:28} {out.style(when, 'dim')}")
+        for path in s.changed:
+            out.detail(f"changed: {path}", indent=11)
+    for p in problems:
+        out.line(out.style(f"CORRUPT    {p}", "red"))
+    if args.ci:
+        return OK if rows and all(s.trusted for s in rows) and not problems else GATE_FAILED
+    return OK
+
+
+def cmd_report(args, out: Output) -> int:
+    cfg = load_config(args)
+    data = report.build(cfg)
+    if out.json_mode or args.format == "json":
+        out.json_mode = True
+        out.emit(data)
+    else:
+        print(report.markdown(data))
+    return OK
+
+
+def cmd_prove(args, out: Output) -> int:
+    root = find_root(Path(args.dir))
+    base = args.base or git.default_base(root)
+    result = prove.prove(root, args.test_command, base, tests=args.tests or None, expect=args.expect, cwd=args.cwd)
+    out.emit({
+        "verdict": result.verdict, "summary": result.summary, "tests": result.tests,
+        "base": result.base.__dict__ if result.base else None, "head": result.head.__dict__ if result.head else None,
+    })  # fmt: skip
+    out.line(f"{out.badge(result.verdict, VERDICT_STYLE, 6)}{result.summary}")
+    for t in result.tests:
+        out.detail(f"test: {t}")
+    if result.base and result.verdict != "pass":
+        out.detail(f"merge base run (exit {result.base.returncode}):")
+        for line in result.base.tail[-12:]:
+            out.detail(line, indent=8)
+    return OK if result.verdict == "pass" else GATE_FAILED
+
+
+def cmd_ledger(args, out: Output) -> int:
+    """Check every verdict file; with --prune, remove verdicts for checks no longer declared."""
+    cfg = load_config(args)
+    verdicts = ledger.read_all(cfg.root)
+    problems = ledger.problems(cfg.root)
+    declared = {c.id for c in cfg.checks}
+    orphans = [k for k, v in verdicts.items() if k not in declared and v.get("kind") != "proof" and "invalid" not in v]
+    if args.prune:
+        for check_id in orphans:
+            ledger.verdict_path(cfg.root, check_id).unlink(missing_ok=True)
+    out.emit({"verdicts": len(verdicts), "problems": problems, "orphans": orphans, "pruned": bool(args.prune)})
+    out.line(f"{len(verdicts)} verdict file(s); {len(problems)} corrupt")
+    for p in problems:
+        out.detail(p, indent=2)
+    if orphans:
+        verb = "removed" if args.prune else "for checks no longer in rung.toml (remove with --prune)"
+        out.line(f"{len(orphans)} verdict(s) {verb}: {', '.join(orphans)}")
+    return GATE_FAILED if problems else OK