osaudit 0.1.0__tar.gz

osaudit-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+plan-*.md
+dist/
+memory/

osaudit-0.1.0/CONVENTIONS.md

@@ -0,0 +1,60 @@
+# Conventions of an automated open-science audit
+
+A paper is auditable when every claim in it can be traced, mechanically, to the evidence that supports it.
+This document states what a paper repository must contain, and in which format, so that `osaudit` can audit it.
+Each rule is normative (MUST) and names the failure it prevents. Rule ids (`numbers/…`) are those printed by `osaudit`.
+
+## Repository
+
+- The repository root holds `audit.toml`, which declares where the paper, the results and the ledgers are. *Prevents: an audit that silently checks nothing because it looked in the wrong place.*
+- The paper is LaTeX sources or a PDF. When both exist, the LaTeX sources are audited. *Prevents: auditing a stale PDF that no longer matches the sources.*
+- Every machine-readable file of the audit (configuration, derivations, ledgers) is TOML. *Prevents: two parsers, two sets of quoting rules, two ways to be wrong.*
+- An entry of `audit.toml` that matches nothing in the paper is a defect, and is reported. *Prevents: allow-lists and derivations that outlive the text they justified.*
+
+## Numbers
+
+- Every number printed in the paper is a results value, a declared derivation of results values, or an allow-list entry with a reason (`numbers/untraced`). *Prevents: an untraced number, such as a breakdown found in no results file, and different when recomputed.*
+- Results are JSON files produced by a committed instrument; a value is named `<file stem>.<key>.<key>…`. *Prevents: numbers copied by hand from a terminal.*
+- A printed number with d decimals matches a value v when it equals v, or 100·v for a percent, within half a unit of its last digit. *Prevents: false alarms on correct rounding (0.6745 printed 67.5%, or 67.4% when rounding half to even).*
+- A number that is a sum, difference, product or share of results values is declared in `[[numbers.derive]]` with its expression (`value = "296"`, `expr = "survey.responses - survey.complete"`). *Prevents: derived numbers that no one can recompute, and a matcher that guesses derivations.*
+- A declared derivation that evaluates to another value than the printed one is a defect (`numbers/derive-mismatch`). *Prevents: a number that drifted after the results were regenerated.*
+- An expression that names a value absent from the results is a defect (`numbers/derive-unknown`). *Prevents: derivations over results that were renamed or removed.*
+- A number that is not produced by the study (a year, a count published by a cited source, a parameter of the method) is allow-listed with `reason`, and with `cite` when it comes from a source (`[[numbers.allow]]`). *Prevents: an unexplained exemption.*
+- A number taken from a cited source agrees with that source, verbatim. "Equals" is said only of equal numbers. *Prevents: a count claimed to equal a published count that differs from it in the fourth digit.*
+- A number inside a verbatim quote is audited as part of the quote, not as a number. *Prevents: reporting a source's numbers as the study's.*
+- Counts of parts add up to the whole that the text states, and each part is named ("8 runs: 6 pass, of which 1 with all tests skipped, 2 cannot start"). *Prevents: arithmetic that does not close.*
+- The same quantity has the same value in every section; a different population is named and its difference explained ("1,204 of the 1,500 responses are complete, the 296 others are partial"). *Prevents: counts that silently differ across sections.*
+
+## Results
+
+- Every results file is a JSON object with a `provenance` block: `command` (argv), `cwd`, `inputs` (each `path` with its `sha256`), `commit` (git commit of the instruments), `now` (time anchor, ISO 8601 with time zone). `osaudit run` writes it (`results/no-provenance`). *Prevents: results that cannot be tied to the command and the data they claim to describe.*
+- Results are produced from committed instruments: the instruments (`[results] instruments` in `audit.toml`) are unchanged since the recorded commit (`results/stale`). A results file that depends on only some of them declares them in `[[results.depends]]` (`file`, `instruments`). *Prevents: results of a version of the code that no longer exists, without rerunning every instrument for every change.*
+- An input is a frozen snapshot: a directory input hashes as the manifest of its files, so a live directory (a log store that grows every day) never matches its record (`results/input-changed`, `results/input-missing`, with `--inputs`). *Prevents: results that no one can recompute, even with the same code.*
+- Re-running the recorded command at the recorded time anchor prints the same results (`results/not-reproduced`, with `--rerun`). *Prevents: results that no instrument can produce any more, and numbers edited by hand.*
+- An instrument never reads the clock or a file time: a time-dependent value (an age, a duration until now) is computed against the anchor in `$OSAUDIT_NOW`, recorded as `provenance.now` (`results/wall-clock`). A justified exception carries `osaudit: allow results/wall-clock -- <reason>` in a comment on the same line. *Prevents: values that shift between runs, such as ages computed against `now()` at analysis time, or against the modification time of a file.*
+- A results file made by a person (a manual check of an automated classifier) is declared in `[[results.manual]]` with `file`, `by`, `date`, `reason`, and is exempt from provenance. *Prevents: a human judgment passed off as an instrument output, or rejected for not being one.*
+- An exemption or a dependency entry that applies to nothing, inline or in `audit.toml`, is a defect (`results/unused`). *Prevents: exemptions that outlive the code they justified.*
+- Every instrument is tested on a known-positive, a known-negative and a boundary case. *Prevents: trusting the numbers of an unvalidated instrument.*
+
+## Quotes
+
+- Every verbatim quote with a citation in the same sentence has an entry in the quote ledger, the `[[quotes]]` entries of `audit.toml` (`quotes/no-entry`). *Prevents: a quote no one checked.*
+- A ledger entry records the citation `key`, the full sentence `text` verbatim, the `version` read (`publisher`, `author-pdf`, `preprint`, `reprint`, `abstract`, `secondary`), its `url`, the `page`, the `date` read and the `status` (`verified` or `unverified`), optionally the `claim` it supports. *Prevents: losing which text was actually read.*
+- The quote of the paper is verbatim in the entry's text; `[...]` marks a cut (`quotes/mismatch`). *Prevents: a quote reworded, or attributed to a text that does not contain it.*
+- The page cited is the page recorded (`quotes/page`), and an entry read in a paged version records its page (`quotes/no-page`). *Prevents: a page no one read.*
+- Only a `verified` entry is quoted (`quotes/unverified`); an entry that matches no quote is removed (`quotes/unused`). *Prevents: quoting before checking, and a ledger that drifts from the paper.*
+- A quote is `verified` only when its wording was matched against the version read; a summary by a search engine or a model is never a version read. *Prevents: a sentence that summaries attribute to an author, but that is not in the text.*
+- The version read is the version cited; when they differ, the numbers and pages are those of the version cited, or the citation changes. *Prevents: citing a published version with the numbers of its preprint, which differ.*
+- A quote from an abstract has no page and the ledger says `abstract`; a page read from a reprint is not the page of the original. *Prevents: invented page numbers.*
+- A shortened quote keeps the scope of the full sentence; the ledger holds the full sentence. *Prevents: a truncated quote that widens the author's claim, such as a quote that drops "some of".*
+
+## References
+
+- A source is cited for a position it holds, not for one it refutes or does not address; the ledger entry records the claim the citation supports. *Prevents: citing a paper for the position it refutes, or a study of one measure for another measure.*
+- Every cited BibTeX entry has a verification record (date, what was checked, against which source) and a DOI or a URL. *Prevents: references with invented fields.*
+- Every cross-reference resolves, and the text names what it points to. *Prevents: text pointing to an example removed in an earlier revision.*
+
+## Reviews
+
+- Every finding of an automated reviewer is a claim, verified by a tool before it is acted on. *Prevents: changing the author's prose for a style defect that the reviewer reported and the prose checker does not confirm.*
+- A verified finding is reported with the tool output that confirms it; an unconfirmed finding is reported as unconfirmed, never acted on. *Prevents: reviewer hallucinations entering the paper as corrections.*

osaudit-0.1.0/LICENSE

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

osaudit-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: osaudit
+Version: 0.1.0
+Summary: Automated open-science audit: trace every claim of a paper to its evidence
+Project-URL: Homepage, https://github.com/ASSERT-KTH/osaudit
+Project-URL: Issues, https://github.com/ASSERT-KTH/osaudit/issues
+Author: Martin Monperrus
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,citations,latex,open science,provenance,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Text Processing :: Markup :: LaTeX
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# osaudit
+
+Automated open-science audit: report every claim of a scientific paper that is not traced, mechanically, to the evidence that supports it. A number to a results file, a quote to a page of a verified source, a result to the instrument and the input that produced it. Silent when everything is traced.
+
+What a paper repository must contain to be auditable is in [CONVENTIONS.md](CONVENTIONS.md).
+
+## Install
+
+    uv venv && uv pip install -e '.[dev]'
+
+PDF input needs `pdftotext` (poppler-utils).
+
+## Usage
+
+In the paper repository, write `audit.toml`:
+
+```toml
+[paper]
+tex = ["paper/sections/*.tex"]      # or: pdf = "paper/main.pdf"
+
+[results]                           # optional: a paper without a study audits its quotes only
+files = ["study/results/*.json"]
+instruments = ["study/*.py"]        # the code that produces the results
+
+[[results.depends]]                 # optional: what one results file depends on (default: all)
+file = "study/results/survey.json"
+instruments = ["study/survey.py", "study/_common.py"]
+
+[[results.manual]]                  # a results file made by a person
+file = "study/results/labels_check.json"
+by = "A. Author"
+date = "2026-10-17"
+reason = "the author checked 20 labels of the classifier"
+
+[[numbers.derive]]                  # a number computed from results values
+value = "392"
+expr = "panel.overall.total - panel.overall.answers.yes"
+
+[[numbers.allow]]                   # a number the study does not produce
+value = "2,000,000"
+reason = "population size published by the cited census"
+cite = "census2020"
+
+[[quotes]]                          # a quote as read in its source
+key = "doe2001archive"              # BibTeX key
+text = "We call the archive the second memory of a laboratory, after the minds of its members."
+version = "publisher"               # publisher|author-pdf|preprint|reprint|abstract|secondary
+url = "https://doi.org/10.1000/doe2001"
+page = "12"                         # omitted for an abstract
+date = "2026-10-01"                 # read on
+status = "verified"                 # verified|unverified
+```
+
+Then:
+
+    osaudit                     # every check (static parts)
+    osaudit numbers             # every printed number traced to results, derivation or allow
+    osaudit quotes              # every cited quote verbatim in a verified [[quotes]] entry
+    osaudit results             # every results file has a provenance that still holds
+    osaudit results --inputs    # ... and its inputs still have their recorded sha256
+    osaudit results --rerun     # ... and its command, rerun at its time anchor, prints the same
+    osaudit CHECK --json        # a JSON array of findings, [] when clean
+    osaudit CHECK --root PATH --config FILE
+
+One line per finding, `file:line: rule: message` (for a PDF, the line is the page):
+
+    paper/results.tex:6: numbers/untraced: 392 matches no results value, derivation or allow entry; candidate expr: panel.overall.total - panel.overall.answers.yes | survey.complete - panel.overall.answers.yes
+    audit.toml:8: numbers/derive-mismatch: 70.0% declared, but ages.by_age["<30"].holds / ages.by_age["<30"].informative = 0.625, printed 62.5%
+    paper.tex:2: quotes/mismatch: ``the only memory of a laboratory'' is not verbatim in the entry of doe2001archive (closest: audit.toml:4)
+    study/results/survey.json:1: results/no-provenance: no 'provenance' block
+    study/ages.py:12: results/wall-clock: datetime.now( reads the clock or a file time; read the time anchor from $OSAUDIT_NOW instead
+
+Exit status: 0 clean, 1 findings, 2 the audit could not run (configuration, input).
+
+### Producing results
+
+Produce each results file through `osaudit run`, which records its provenance (command, inputs and their sha256, git commit, time anchor) in the file:
+
+    osaudit run --input data/answers.csv -o study/results/survey.json -- python study/survey.py data/answers.csv
+
+The instrument prints its results as a JSON object on stdout, and reads the time anchor from `$OSAUDIT_NOW` instead of the clock. Its instruments must be committed; `run` refuses otherwise. A clock read that is justified carries `# osaudit: allow results/wall-clock -- <reason>` on its line.
+
+### Results values
+
+The `provenance` block is not a result and is never matched. A value is named `<file stem>.<key>...`, with `["key"]` for keys that are not identifiers and `[i]` for list indices: `ages.by_age["<30"].share`. A printed number matches a value within half a unit of its last digit; a percent matches 100·v. Expressions allow `+ - * /`, parentheses and numeric constants, and are never evaluated as Python.
+
+Candidates proposed for an untraced number are single operations over counts (sums, differences, shares), ranked by closeness in the results tree. They are hints: nothing is accepted until written into `audit.toml`.
+
+### What is not audited as a number
+
+LaTeX comments, `tikzpicture` and verbatim environments, verbatim quotes (` ``...'' `, audited as quotes), arguments of `\input \label \cref \cite \url \begin` and similar, parts of a document (`Section 4.3`, `Table~1`, `p.~107`), and numbers glued to a word (`123d0d04`, `3.0cm`, `RQ1`). In a PDF: numbered citations, list labels, lines holding only a number, and everything after the last "References" heading.
+
+### Quotes
+
+A quote is ` ``...'' ` with a citation in the same sentence (the nearest after it, else before it); its page is the `p.~X` of that citation. It must be verbatim, after normalization of LaTeX, typography and case, in the full sentence of an entry for that key; `[...]` marks a cut. In a PDF, citations are numbered, so a quote `“...”` matches any entry by its text.
+
+## Status
+
+`numbers`, `quotes`, `results` and `run` are implemented. `refs` and `review` are specified in CONVENTIONS.md and not yet built; they will be subcommands of `osaudit` too.
+
+## License
+
+MIT

osaudit-0.1.0/README.md

@@ -0,0 +1,103 @@
+# osaudit
+
+Automated open-science audit: report every claim of a scientific paper that is not traced, mechanically, to the evidence that supports it. A number to a results file, a quote to a page of a verified source, a result to the instrument and the input that produced it. Silent when everything is traced.
+
+What a paper repository must contain to be auditable is in [CONVENTIONS.md](CONVENTIONS.md).
+
+## Install
+
+    uv venv && uv pip install -e '.[dev]'
+
+PDF input needs `pdftotext` (poppler-utils).
+
+## Usage
+
+In the paper repository, write `audit.toml`:
+
+```toml
+[paper]
+tex = ["paper/sections/*.tex"]      # or: pdf = "paper/main.pdf"
+
+[results]                           # optional: a paper without a study audits its quotes only
+files = ["study/results/*.json"]
+instruments = ["study/*.py"]        # the code that produces the results
+
+[[results.depends]]                 # optional: what one results file depends on (default: all)
+file = "study/results/survey.json"
+instruments = ["study/survey.py", "study/_common.py"]
+
+[[results.manual]]                  # a results file made by a person
+file = "study/results/labels_check.json"
+by = "A. Author"
+date = "2026-10-17"
+reason = "the author checked 20 labels of the classifier"
+
+[[numbers.derive]]                  # a number computed from results values
+value = "392"
+expr = "panel.overall.total - panel.overall.answers.yes"
+
+[[numbers.allow]]                   # a number the study does not produce
+value = "2,000,000"
+reason = "population size published by the cited census"
+cite = "census2020"
+
+[[quotes]]                          # a quote as read in its source
+key = "doe2001archive"              # BibTeX key
+text = "We call the archive the second memory of a laboratory, after the minds of its members."
+version = "publisher"               # publisher|author-pdf|preprint|reprint|abstract|secondary
+url = "https://doi.org/10.1000/doe2001"
+page = "12"                         # omitted for an abstract
+date = "2026-10-01"                 # read on
+status = "verified"                 # verified|unverified
+```
+
+Then:
+
+    osaudit                     # every check (static parts)
+    osaudit numbers             # every printed number traced to results, derivation or allow
+    osaudit quotes              # every cited quote verbatim in a verified [[quotes]] entry
+    osaudit results             # every results file has a provenance that still holds
+    osaudit results --inputs    # ... and its inputs still have their recorded sha256
+    osaudit results --rerun     # ... and its command, rerun at its time anchor, prints the same
+    osaudit CHECK --json        # a JSON array of findings, [] when clean
+    osaudit CHECK --root PATH --config FILE
+
+One line per finding, `file:line: rule: message` (for a PDF, the line is the page):
+
+    paper/results.tex:6: numbers/untraced: 392 matches no results value, derivation or allow entry; candidate expr: panel.overall.total - panel.overall.answers.yes | survey.complete - panel.overall.answers.yes
+    audit.toml:8: numbers/derive-mismatch: 70.0% declared, but ages.by_age["<30"].holds / ages.by_age["<30"].informative = 0.625, printed 62.5%
+    paper.tex:2: quotes/mismatch: ``the only memory of a laboratory'' is not verbatim in the entry of doe2001archive (closest: audit.toml:4)
+    study/results/survey.json:1: results/no-provenance: no 'provenance' block
+    study/ages.py:12: results/wall-clock: datetime.now( reads the clock or a file time; read the time anchor from $OSAUDIT_NOW instead
+
+Exit status: 0 clean, 1 findings, 2 the audit could not run (configuration, input).
+
+### Producing results
+
+Produce each results file through `osaudit run`, which records its provenance (command, inputs and their sha256, git commit, time anchor) in the file:
+
+    osaudit run --input data/answers.csv -o study/results/survey.json -- python study/survey.py data/answers.csv
+
+The instrument prints its results as a JSON object on stdout, and reads the time anchor from `$OSAUDIT_NOW` instead of the clock. Its instruments must be committed; `run` refuses otherwise. A clock read that is justified carries `# osaudit: allow results/wall-clock -- <reason>` on its line.
+
+### Results values
+
+The `provenance` block is not a result and is never matched. A value is named `<file stem>.<key>...`, with `["key"]` for keys that are not identifiers and `[i]` for list indices: `ages.by_age["<30"].share`. A printed number matches a value within half a unit of its last digit; a percent matches 100·v. Expressions allow `+ - * /`, parentheses and numeric constants, and are never evaluated as Python.
+
+Candidates proposed for an untraced number are single operations over counts (sums, differences, shares), ranked by closeness in the results tree. They are hints: nothing is accepted until written into `audit.toml`.
+
+### What is not audited as a number
+
+LaTeX comments, `tikzpicture` and verbatim environments, verbatim quotes (` ``...'' `, audited as quotes), arguments of `\input \label \cref \cite \url \begin` and similar, parts of a document (`Section 4.3`, `Table~1`, `p.~107`), and numbers glued to a word (`123d0d04`, `3.0cm`, `RQ1`). In a PDF: numbered citations, list labels, lines holding only a number, and everything after the last "References" heading.
+
+### Quotes
+
+A quote is ` ``...'' ` with a citation in the same sentence (the nearest after it, else before it); its page is the `p.~X` of that citation. It must be verbatim, after normalization of LaTeX, typography and case, in the full sentence of an entry for that key; `[...]` marks a cut. In a PDF, citations are numbered, so a quote `“...”` matches any entry by its text.
+
+## Status
+
+`numbers`, `quotes`, `results` and `run` are implemented. `refs` and `review` are specified in CONVENTIONS.md and not yet built; they will be subcommands of `osaudit` too.
+
+## License
+
+MIT

osaudit-0.1.0/osaudit/__init__.py

@@ -0,0 +1,3 @@
+"""osaudit: trace every claim of a scientific paper to the evidence that supports it."""
+
+__version__ = "0.1.0"

osaudit-0.1.0/osaudit/__main__.py

@@ -0,0 +1,7 @@
+"""Run `python -m osaudit`."""
+
+from __future__ import annotations
+
+from ._cli import main
+
+raise SystemExit(main())

osaudit-0.1.0/osaudit/_cli.py

@@ -0,0 +1,114 @@
+"""The `osaudit` command line: silent when the paper is clean, one line per finding otherwise.
+
+Exit status: 0 no finding, 1 findings, 2 the audit could not run (configuration, input).
+`osaudit run` writes a results file with its provenance; it prints nothing on success.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from . import __version__, _numbers, _provenance, _quotes, _results_check
+from ._config import Config, ConfigError, instruments, load
+from ._findings import Finding
+from ._git import GitError
+from ._pdf import PdfError
+
+
+def _results(cfg: Config, args: argparse.Namespace) -> list[Finding]:
+    return _results_check.check(cfg, inputs=getattr(args, "inputs", False),
+                                rerun=getattr(args, "rerun", False),
+                                timeout=getattr(args, "timeout", None))
+
+
+CHECKS: dict[str, tuple[Callable[[Config, argparse.Namespace], list[Finding]], str]] = {
+    "numbers": (lambda cfg, _: _numbers.check(cfg),
+                "every number of the paper traced to results, derivation or allow"),
+    "quotes": (lambda cfg, _: _quotes.check(cfg),
+               "every cited verbatim quote in a verified [[quotes]] entry, with its page"),
+    "results": (_results,"every results file has a provenance that still holds "
+                          "(static; --inputs, --rerun to go further)"),
+}
+
+
+def parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="osaudit",
+        description="Audit a paper repository: report every claim not traced to its evidence. "
+                    "Silent when clean; `file:line: rule: message` per finding. "
+                    "Conventions: CONVENTIONS.md. Without a check name, runs every check "
+                    "(static parts only).",
+        epilog="exit status: 0 clean, 1 findings, 2 the audit could not run",
+    )
+    p.add_argument("--version", action="version", version=f"osaudit {__version__}")
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--root", type=Path, default=Path("."),
+                        help="paper repository (default: current directory)")
+    common.add_argument("--config", type=Path, help="audit.toml (default: <root>/audit.toml)")
+    common.add_argument("--json", action="store_true",
+                        help="print findings as a JSON array ([] when clean)")
+    sub = p.add_subparsers(dest="check", metavar="CHECK")
+    for name, (_, help_) in CHECKS.items():
+        sp = sub.add_parser(name, parents=[common], help=help_, description=help_)
+        if name == "results":
+            sp.add_argument("--inputs", action="store_true",
+                            help="rehash every recorded input (needs the inputs)")
+            sp.add_argument("--rerun", action="store_true",
+                            help="rerun every recorded command at its time anchor and compare")
+            sp.add_argument("--timeout", type=float, help="seconds per rerun")
+    sub.add_parser("all", parents=[common], help="run every check (the default)")
+    run = sub.add_parser(
+        "run", help="run an instrument, write its JSON results with their provenance",
+        description="Run CMD (its stdout must be a JSON object) with the time anchor in "
+                    f"${_provenance.ENV_NOW}, and write the object to OUTPUT with a provenance "
+                    "block: command, inputs and their sha256, git commit, time anchor. "
+                    "Refuses to run on a tree with uncommitted changes.",
+        epilog="example: osaudit run --input data/answers.csv -o results/survey.json -- "
+               "python study/survey.py data/answers.csv")
+    run.add_argument("--root", type=Path, default=Path("."), help="repository of the instruments")
+    run.add_argument("--input", type=Path, action="append", default=[], dest="input_paths",
+                     help="an input file or directory (repeat for each)")
+    run.add_argument("-o", "--output", type=Path, required=True, help="results file to write")
+    run.add_argument("cmd", nargs=argparse.REMAINDER, help="-- CMD [ARG ...]")
+    return p
+
+
+def _run(args: argparse.Namespace) -> int:
+    cmd = args.cmd[1:] if args.cmd[:1] == ["--"] else args.cmd
+    if not cmd:
+        print("osaudit run: no command (put it after --)", file=sys.stderr)
+        return 2
+    root = args.root.resolve()
+    try:
+        output = args.output.resolve()
+        out_rel = str(output.relative_to(root)) if output.is_relative_to(root) else str(output)
+        _provenance.run(root, cmd, args.input_paths, args.output, instruments(root, out_rel))
+    except (_provenance.RunError, ConfigError, GitError, OSError) as e:
+        print(f"osaudit run: {e}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not (argv and argv[0] in (*CHECKS, "all", "run", "-h", "--help", "--version")):
+        argv = ["all", *argv]
+    args = parser().parse_args(argv)
+    if args.check == "run":
+        return _run(args)
+    names = list(CHECKS) if args.check == "all" else [args.check]
+    try:
+        cfg = load(args.root.resolve(), args.config.resolve() if args.config else None)
+        findings = [f for n in names for f in CHECKS[n][0](cfg, args)]
+    except (ConfigError, PdfError, GitError, OSError, ValueError) as e:
+        print(f"osaudit: {e}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps([f.as_json() for f in findings], indent=1))
+    else:
+        sys.stdout.write("".join(f"{f}\n" for f in findings))
+    return 1 if findings else 0