attestation 0.2.0__tar.gz

attestation-0.2.0/.claude/agents/attestation-feed.md

@@ -0,0 +1,26 @@
+---
+name: attestation-feed
+description: Read and search the science feed, and manage what it subscribes to.
+tools: feed
+---
+
+<!-- Generated by `attest emit` from attestation.mcp.AGENT_SURFACES. Edits here are reported by `attest emit`, never overwritten. -->
+
+## Your job
+
+Help this reader keep up with the literature. The corpus is their own
+subscribed feeds -- mostly arXiv, plus Nature, Scientific Reports, Hugging
+Face and HN -- so questions like "find me recent papers on X", "what should
+I read this week" and "what's new in Y" are YOURS to answer, locally,
+without any network call. Reach for feed.ask when the question is in plain
+words. Reading an item is itself feedback: it trains the ranker, so open
+what looks relevant rather than only listing titles.
+
+## Why this agent is separate
+
+Conversational; a wrong guess costs a retry.
+
+Run with `ATTEST_TOOLS=feed`. Tools outside `feed` are not
+registered for this agent: they are absent rather than merely
+undocumented, because a model that can see a tool will eventually
+call it.

attestation-0.2.0/.claude/agents/attestation-knowledge.md

@@ -0,0 +1,23 @@
+---
+name: attestation-knowledge
+description: Explore the reading knowledge graph, the items behind it, and the references they cite.
+tools: cite, feed.search, kg
+---
+
+<!-- Generated by `attest emit` from attestation.mcp.AGENT_SURFACES. Edits here are reported by `attest emit`, never overwritten. -->
+
+## Your job
+
+Answer "what have I been reading about", "how do these two topics connect"
+and "what are my main research areas", from the concept graph built out of
+this reader's own items. Concept names are lowercase and hyphenated; turn a
+user's phrasing into one with kg.concepts before looking it up.
+
+## Why this agent is separate
+
+Exploratory, read-only.
+
+Run with `ATTEST_TOOLS=knowledge`. Tools outside `cite, feed.search, kg` are not
+registered for this agent: they are absent rather than merely
+undocumented, because a model that can see a tool will eventually
+call it.

attestation-0.2.0/.claude/agents/attestation-provenance.md

@@ -0,0 +1,25 @@
+---
+name: attestation-provenance
+description: Scan experiment runs, compare arms, and check claims against them.
+tools: cite.check, runs
+---
+
+<!-- Generated by `attest emit` from attestation.mcp.AGENT_SURFACES. Edits here are reported by `attest emit`, never overwritten. -->
+
+## Your job
+
+Answer "which arm actually won, and on what evidence" and "is what my draft
+says still true". You read experiment artifacts already on disk -- no
+instrumentation, no re-running anything. The caveats you return are the
+product, not a disclaimer: relay them verbatim. When a comparison refuses,
+the refusal is the right answer and it names what to do next; do not work
+around it by picking a metric yourself.
+
+## Why this agent is separate
+
+Verification: a wrong answer reaches a manuscript, and the caveats are the product.
+
+Run with `ATTEST_TOOLS=provenance`. Tools outside `cite.check, runs` are not
+registered for this agent: they are absent rather than merely
+undocumented, because a model that can see a tool will eventually
+call it.

attestation-0.2.0/.claude/agents/attestation-symbolic.md

@@ -0,0 +1,22 @@
+---
+name: attestation-symbolic
+description: Symbolic algebra and calculus, in a sandboxed subprocess.
+tools: sym
+---
+
+<!-- Generated by `attest emit` from attestation.mcp.AGENT_SURFACES. Edits here are reported by `attest emit`, never overwritten. -->
+
+## Your job
+
+Do the algebra and calculus exactly, so a derivation in a paper can be
+checked rather than eyeballed. `^` and `2x` both parse. sym.verify reports
+unproven as unproven -- it is never a disproof.
+
+## Why this agent is separate
+
+Sandboxed subprocess, touches no database.
+
+Run with `ATTEST_TOOLS=symbolic`. Tools outside `sym` are not
+registered for this agent: they are absent rather than merely
+undocumented, because a model that can see a tool will eventually
+call it.

attestation-0.2.0/.env.sample

@@ -0,0 +1,124 @@
+# attestation configuration — copy to .env and edit:  cp .env.sample .env
+# Loaded at startup by the `attest` CLI and the MCP server (attest-mcp).
+# Real environment variables always win over values in this file.
+
+# OpenAI-compatible endpoint serving chat + embeddings (Ollama's /v1 by default).
+# Swap backends by pointing this elsewhere (vLLM, llama.cpp server, OpenRouter...).
+LLM_BASE_URL=http://localhost:11434/v1
+
+# API key, sent as a Bearer token when set. Ollama ignores auth; needed for
+# OpenRouter / authenticated vLLM / OpenAI.
+#LLM_API_KEY=
+
+# --- Hosted models instead of Ollama (no GPU, no 7.8 GB download) -------------
+# Any OpenAI-compatible endpoint works. NVIDIA NIM, for example:
+#LLM_BASE_URL=https://integrate.api.nvidia.com/v1
+#LLM_API_KEY=nvapi-...
+#CHAT_MODEL=<a chat model your account can call -- see below>
+#EMBED_MODEL=nvidia/nemotron-3-embed-1b
+# `attest install --check` makes one embedding and one one-token chat request
+# and reports the server's own reason when a model fails. MEASURED 2026-09-11:
+# NIM listed 82 models; nemotron-3-embed-1b answered (2048 dims) while every
+# chat model tried answered 410 (end of life) or 404 (not enabled for the
+# account) -- so pick a chat model from /v1/models and let --check confirm it
+# rather than trusting the catalogue.
+# EMBED_DIMS is a client-side truncation, so a 2048-dim model stores 256 dims
+# unchanged; a model NARROWER than EMBED_DIMS is refused. Switching embedding
+# models means a fresh database (get_db refuses a mismatched reopen).
+# Hosted models send your titles, abstracts and interests text off the machine;
+# the ledger and claim checker never touch a model and stay local either way.
+
+# Chat model for explanations + tagging.
+# gemma4:e2b measured on 2x GTX 1080 (8 GB each), ollama 0.32.9: 2.2 GB
+# resident, 100% GPU, ~2.2s per tagging call, and clean canonical tags.
+# hermes3:3b is smaller but emitted a malformed tag on 40% of items, and
+# gemma4:12b partially CPU-offloads on 8 GB-class cards (~60-90s/call).
+# NB: gemma4:e2b needs ollama >= 0.32.9 (earlier builds abort with
+# GGML_ASSERT in the graph scheduler). This is a MANUAL requirement: nothing
+# in this repo checks the daemon version (`attest install`/`--check` verify
+# model presence, not Ollama's version) -- run `ollama --version` yourself.
+CHAT_MODEL=gemma4:e2b-it-q4_K_M
+
+# Embedding model.
+#EMBED_MODEL=embeddinggemma
+
+# Stored embedding dimensionality (Matryoshka truncation, client-side).
+# WARNING: changing this invalidates every stored vector — delete the database
+# and re-ingest. get_db() refuses to open a mismatched database.
+#EMBED_DIMS=256
+
+# Database path override (default resolution order is documented in the README).
+# RSS_DB, the pre-rename name, is still honoured when ATTEST_DB is unset.
+#ATTEST_DB=/home/you/.hermes/skills/science-recommendations/data/hermes.db
+#RSS_DB=
+
+# The agent home every other path hangs off: skills, the refresh script and its
+# lock, the citation cache, the ledger's config fallback, and where a legacy
+# skill-data database is looked for. Unset, ~/.hermes -- which is right on a
+# laptop with one agent and wrong on a provisioned box, where `attest install`
+# would otherwise write into the operator's real Hermes home.
+# ATTEST_DB above still wins for the database specifically.
+#HERMES_HOME=/home/you/.agent37-pilots/instances/research/.hermes
+
+# Which libraries feed citations and `attest library sync`. Unset, every *.bib
+# in the current directory and Zotero's default ~/Zotero/zotero.sqlite.
+# ATTEST_BIB_PATHS is os.pathsep-separated (":" on Linux/macOS).
+#ATTEST_BIB_PATHS=/home/you/papers/refs.bib:/home/you/thesis/thesis.bib
+#ATTEST_ZOTERO_PATH=/home/you/Zotero/zotero.sqlite
+
+# The settings that allow a network call. Unset, every citation lookup and
+# library sync is local (Zotero + *.bib + the feed). ATTEST_CITATION_WEB
+# (anything but 0/false) arms CrossRef and the arXiv API: metadata for
+# references the library already holds -- they never add a paper on their
+# own. ATTEST_CITATION_SCHOLAR arms Semantic Scholar reference lists, a second flag
+# because it is a larger, rate-limited surface (one request per second,
+# cached forever). Both are read when readers are BUILT, not per call;
+# `cite.sources()` reports what is live.
+#ATTEST_CITATION_WEB=1
+#ATTEST_CITATION_SCHOLAR=1
+
+# Paper research (standing topics as research: feeds, the feed.research tool
+# and full text) reaches arXiv, PubMed and CrossRef. ON by default: `attest
+# ingest` already fetches RSS over the network and a topic query is the same
+# class of call in the same command. Set to 0 to make every research client a
+# no-op that reports `offline`. Read once when the clients are built.
+#ATTEST_RESEARCH_WEB=1
+# Optional NCBI key: PubMed allows 3 requests/s without one, 10 with.
+#NCBI_API_KEY=
+
+# Where `attest runs scan` looks for experiment artifacts when no path is
+# given. The ledger reads finished runs off disk and needs no model, so this is
+# the one setting that matters for the provenance half of the tool.
+#RESEARCH_ROOT=/home/you/projects
+
+# --- Agent surface selection (set per MCP server entry, not usually here) -----
+# ATTEST_TOOLS restricts a session to ONE namespace, so a tool outside its
+# remit is absent rather than merely undocumented. Measured on gemma4:e2b: one
+# agent choosing among the full flat surface answered 8/15; four restricted
+# agents plus deterministic routers answered 13/15. `attest emit` generates the
+# per-surface config entries, so you rarely set this by hand.
+#   feed | provenance | knowledge | symbolic   (an unknown value RAISES)
+#ATTEST_TOOLS=feed
+
+# Reveal a surface's specific tools from the start instead of only its `.ask`
+# router. Measured: with the specifics visible the model picked the router 1
+# time in 26; with only the router visible, 26 in 26. Leave unset unless a
+# caller already knows exactly which tool it wants.
+#ATTEST_EXPAND=1
+
+# --- Ollama SERVER settings (read by the ollama daemon, NOT by hermes) --------
+# Set these in the environment that launches `ollama serve` (e.g. its systemd
+# unit), not here. /v1 requests cannot pin models or set context length, so
+# these replace the per-request keep_alive/num_ctx knobs of the native API.
+#OLLAMA_MAX_LOADED_MODELS=2   # keep chat + embed models co-resident
+#OLLAMA_KEEP_ALIVE=30m        # hold models this long (matches `attest warmup`)
+# NOT -1. That pins models until the year 2318: measured at 5.4GB held and OOM
+# kills on a 23GB box, because nothing ever releases them.
+#OLLAMA_CONTEXT_LENGTH=32768   # context window for /v1 requests
+# 32768 is a floor, not a suggestion. Ollama defaults to 4096, which silently
+# truncates the tool list mid-JSON -- the tools then appear not to exist rather
+# than failing, which is far harder to diagnose than an error.
+
+# An optimized tagging-prompt artifact (evals/prompts/*.json) for `attest tag`.
+# Unset = the hand-written prompt. Produced offline by evals/optimize_tagging.py.
+#ATTEST_TAG_PROMPT=

attestation-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,160 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  gates:
+    name: gates (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    env:
+      # macos-latest ships a python.org framework build at
+      # /Library/Frameworks/Python.framework, and uv picks it over its own
+      # managed CPython when the version matches. That build has no
+      # sqlite3 loadable-extension support, so sqlite-vec cannot load and
+      # db.get_db() dies at conn.enable_load_extension (254 failures on the
+      # first CI run, 2026-08-28). uv's managed builds enable it on every OS.
+      UV_PYTHON_PREFERENCE: only-managed
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+      - name: ruff check
+        run: uv run ruff check .
+
+      - name: ty check
+        run: uv run ty check src/
+
+      - name: uv.lock is in sync with pyproject.toml
+        run: uv lock --check
+
+      - name: complexity ratchet (radon)
+        run: uv run python scripts/check_complexity.py
+
+      - name: bandit (security)
+        run: uv run bandit -q -c pyproject.toml -r src/attestation --severity-level medium
+
+      - name: xenon (maintainability)
+        run: uv run xenon --max-modules B --max-average A src/attestation
+
+      - name: pytest
+        run: uv run pytest -q
+
+  wheel-smoke:
+    name: wheel smoke test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build wheel
+        run: uv build
+
+      - name: Install wheel into a clean venv
+        run: |
+          python3 -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/pip install --quiet dist/*.whl
+
+      - name: attest --help exits 0
+        run: /tmp/wheel-venv/bin/attest --help
+
+      - name: attestation.server imports cleanly
+        run: /tmp/wheel-venv/bin/python -c "import attestation.server"
+
+      - name: feeds.toml is packaged
+        # Regression insurance: the advertised `uvx --from git+... attest ingest`
+        # on-ramp reads attestation/feeds.toml out of the installed package, so
+        # a repackaging that drops it breaks first-run ingest silently.
+        run: |
+          /tmp/wheel-venv/bin/python -c "
+          import importlib.resources as r
+          p = r.files('attestation').joinpath('feeds.toml')
+          assert p.is_file(), 'attestation/feeds.toml missing from installed wheel'
+          print('feeds.toml present in wheel:', p)
+          "
+
+      - name: py.typed is packaged
+        # Same regression insurance as feeds.toml above: a downstream type
+        # checker treats a package with no py.typed as untyped and ignores
+        # its annotations, silently, even though this repo checks them with
+        # `ty` on every commit.
+        run: |
+          /tmp/wheel-venv/bin/python -c "
+          import importlib.resources as r
+          p = r.files('attestation').joinpath('py.typed')
+          assert p.is_file(), 'attestation/py.typed missing from installed wheel'
+          print('py.typed present in wheel:', p)
+          "
+
+  flows:
+    name: example flows (offline)
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON_PREFERENCE: only-managed
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies (with the examples group)
+        run: uv sync --all-extras --dev --group examples
+
+      - name: Every flow, against the stub model server
+        # The demonstration in examples/flows, end to end: the MLflow family,
+        # the persona eval, and every MCP tool over stdio. No Ollama, no
+        # network. Its numbers are about the stub and say so; the point is
+        # that the flows cannot rot.
+        run: uv run python examples/flows/run_all.py --offline
+
+  docs:
+    name: docs site
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON_PREFERENCE: only-managed
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Sync dependencies (with the docs group)
+        run: uv sync --all-extras --dev --group docs
+
+      - name: mkdocs build --strict
+        # A docstring that breaks a cross-reference, or a nav entry in
+        # mkdocs.yml that points nowhere, fails the push here rather than
+        # rotting silently. The `gates` job does not install the docs group,
+        # so this job runs the real build itself.
+        run: uv run --group docs mkdocs build --strict
+
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-site
+          path: site/

attestation-0.2.0/.github/workflows/docs.yml

@@ -0,0 +1,50 @@
+# Deploys the docs site to GitHub Pages from main. The build is the same
+# command the `docs site` job in ci.yml runs (`mkdocs build --strict`), so
+# a page that would fail CI never deploys; this workflow only adds the
+# Pages upload and deploy steps behind it. Pages must be set to deploy from
+# GitHub Actions in the repository settings (done once with
+# `gh api -X POST repos/<owner>/<repo>/pages -f build_type=workflow`).
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      UV_PYTHON_PREFERENCE: only-managed
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - name: Sync dependencies (with the docs group)
+        run: uv sync --all-extras --dev --group docs
+      - name: mkdocs build --strict
+        run: uv run --group docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

attestation-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,64 @@
+name: Release
+
+# Tag-triggered PyPI publish through trusted publishing (OIDC): no API token
+# lives in this repo. One-time setup on pypi.org -> project "attestation" ->
+# Publishing -> add a GitHub publisher with owner mgoldey, repository
+# attestation, workflow release.yml, environment pypi. Then:
+#
+#   git tag v0.2.0 && git push origin v0.2.0
+#
+# The build job refuses a tag that does not match pyproject's version, so a
+# release cannot ship under a number the package does not carry.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: build + smoke
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Tag matches pyproject version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")"
+          test "$tag" = "$version" || { echo "tag v$tag != pyproject version $version" >&2; exit 1; }
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Wheel installs and both console scripts answer
+        run: |
+          python3 -m venv /tmp/wheel-venv
+          /tmp/wheel-venv/bin/pip install --quiet dist/*.whl
+          /tmp/wheel-venv/bin/attest --help >/dev/null
+          /tmp/wheel-venv/bin/attestation --help >/dev/null
+          /tmp/wheel-venv/bin/attest-mcp --help >/dev/null 2>&1 || true
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

attestation-0.2.0/.gitignore

@@ -0,0 +1,48 @@
+.venv/
+__pycache__/
+*.db
+*.db-wal
+*.db-shm
+# Retag/migration snapshots: `*.db` does not match a .bak-retag-<stamp>
+# suffix, so an 8MB copy of the database was one `git add .` from the
+# history it can never be removed from.
+*.db.bak*
+.ruff_cache/
+.pytest_cache/
+.env
+# Credential-bearing env files (neon.env holds a live Postgres password and S3
+# secret keys). `.env` alone does not match `neon.env` or `*.env`.
+*.env
+
+# Local demo recordings: a 5.5MB .webm plus stills, never committed. Kept out
+# of the repo so a clone stays small -- a binary that large is permanent
+# history once added. Host it externally and link from the README if it needs to
+# be shared. demos/*/record.sh and record.py write here by default.
+demo/
+
+# demos/: recording scripts are committed, their .cast/.gif/.webm output and
+# the scratch databases seed_*_db.py builds are not (same reasoning as
+# demo/ above -- regenerable, and a real .cast is a transcript that can
+# carry whatever path ran it). demos/ lives at the repo root, not under
+# examples/, on purpose -- see CLAUDE.md's Golden paths note.
+demos/**/*.cast
+demos/**/*.gif
+demos/**/*.webm
+demos/**/*.db
+
+# Build artifacts: `uv build` / CI wheel smoke test write here.
+dist/
+build/
+.mutate-backup/
+
+# `mkdocs build` output. Built, not deployed; CI's `docs` job uploads it as
+# an artifact instead of committing it. Anchored to the root: `docs/site/`
+# holds a committed, generated page (the design-records index) and must not
+# be swept up by an unanchored `site/`.
+/site/
+
+# Process logs from the superpowers plugin (design/plan transcripts) and a uv
+# cache left by a run with HOME pointed at a fake path: both sat untracked-but-
+# unignored, one `git add .` from becoming permanent history.
+.superpowers/
+nonexistent-home/

attestation-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,100 @@
+# Local hooks only: every tool is already a declared dev dependency, so they
+# run against the versions this project pins. The alternative (pre-commit's own
+# isolated envs) would install a *second* copy of ruff at a version nothing
+# else uses, and drift silently.
+#
+# Entries call `uv run --frozen ...` rather than `.venv/bin/...`: `.venv/` is
+# gitignored, so those paths do not exist on a fresh clone until `uv sync`, and
+# a CI runner using astral-sh/setup-uv need not put its venv at `.venv` at all
+# -- which is the environment .github/workflows/ci.yml runs in. `--frozen`
+# keeps these hooks from ever mutating uv.lock as a side effect.
+#
+# These hooks once called `.venv/bin/...` to route around what looked like a uv
+# bug under pre-commit's scrubbed environment. It was not: the venv had been
+# built at the project's old path and 26 of its console scripts still pointed
+# their shebang at an interpreter that no longer existed. `uv sync` fixed it.
+# See CLAUDE.md "Working here".
+#
+#   uv run pre-commit install        # activate
+#   uv run pre-commit run --all-files
+#   git commit --no-verify           # bypass once, deliberately
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --frozen ruff format
+        language: system
+        types_or: [python, pyi]
+
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --frozen ruff check --fix
+        language: system
+        types_or: [python, pyi]
+
+      - id: ty
+        name: ty (type check)
+        entry: uv run --frozen ty check src/
+        language: system
+        types_or: [python, pyi]
+        # src/ only, and always the whole tree: ty resolves imports across
+        # modules, so checking just the staged files reports errors that a
+        # full run does not, and misses ones it would catch.
+        pass_filenames: false
+
+      - id: uv-lock
+        name: uv.lock matches pyproject.toml
+        entry: uv lock --check
+        language: system
+        files: ^(pyproject\.toml|uv\.lock)$
+        pass_filenames: false
+
+      - id: complexity
+        name: complexity ratchet (radon)
+        entry: uv run --frozen python scripts/check_complexity.py
+        language: system
+        types: [python]
+        pass_filenames: false
+        # Per-file, not global. A single --max-absolute threshold set loose
+        # enough to pass a clean checkout also permits any file to grow a
+        # function at that rank -- verified by adding a 17-branch function and
+        # watching a global gate return 0. Each file is pinned at its own
+        # measured worst instead, so getting worse requires editing the list.
+
+      - id: bandit
+        name: bandit (security)
+        entry: uv run --frozen bandit -q -c pyproject.toml -r src/attestation --severity-level medium
+        language: system
+        types: [python]
+        pass_filenames: false
+        # Medium and above only. At LOW, bandit reports every `import
+        # subprocess` and every partial executable path, which here are 8
+        # deliberate calls with static argv and no shell -- noise that trains
+        # people to ignore the hook. Baseline at adoption: 0 findings at
+        # medium, 0 at high.
+
+      - id: xenon
+        name: xenon (maintainability)
+        entry: uv run --frozen xenon --max-modules B --max-average A src/attestation
+        language: system
+        types: [python]
+        pass_filenames: false
+        # Module and average grades only -- NOT --max-absolute, which was tried
+        # here and found hollow: `--max-absolute D` returned exit 0 against a
+        # 26-branch function. Per-function complexity is enforced by the radon
+        # ratchet above, which pins each file at its own measured worst. This
+        # hook covers what that one does not: a module whose total complexity
+        # creeps up while no single function crosses its own line.
+
+      - id: pytest
+        name: pytest
+        entry: uv run --frozen pytest -q
+        language: system
+        types: [python]
+        pass_filenames: false
+        # The suite is ~50s. That is slow for a hook and worth it here: this
+        # repo's recurring failure has been tests that pass against the bug
+        # they were written to catch, so a green suite is the one signal that
+        # has repeatedly mattered. Drop this hook if it starts being bypassed.
+        stages: [pre-commit]

attestation-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12.12