cleverly 0.1.0__tar.gz

cleverly-0.1.0/.codex/config.toml

@@ -0,0 +1,2 @@
+# Reuse the repository's existing Claude instructions when no AGENTS.md is present.
+project_doc_fallback_filenames = ["CLAUDE.md"]

cleverly-0.1.0/.gitattributes

@@ -0,0 +1,15 @@
+# A checkout must produce the same bytes on every platform, because some of these
+# bytes are hashed.  `tests/studies/evidence/manifest.py` records a sha256 over each
+# published study artifact and `tests/unit/test_method_evidence.py` checks it, so a
+# line ending rewritten at checkout time turns a provenance claim into a statement
+# about the machine that ran `git clone`.  Without this file and with the common
+# `core.autocrlf=true`, the canonical TMLE and CV-TMLE manifests verified on Windows
+# and failed on Linux CI, which is the one thing a byte-exact claim must not do.
+#
+# `text=auto` still lets git detect binary content; `eol=lf` fixes the working-tree
+# ending for everything it does classify as text.  The compressed replicate archives
+# are marked explicitly rather than left to detection, since they are the artifacts
+# whose bytes matter most and a misdetection there would corrupt them silently.
+* text=auto eol=lf
+
+*.gz binary

cleverly-0.1.0/.github/actions/setup-env/action.yml

@@ -0,0 +1,58 @@
+name: Set up cleverly's environment
+description: >-
+  uv, a pinned interpreter, a virtual environment on PATH, and the package installed
+  editable from the committed lock. Jobs that need a working cleverly do this identically.
+
+inputs:
+  python-version:
+    description: The interpreter to install and build the virtual environment against.
+    required: true
+  extra:
+    description: Which optional-dependency group to install; "dev" for anything running pytest.
+    required: false
+    default: dev
+  packages:
+    description: >-
+      Further requirements to install after the locked project, space-separated.
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - uses: astral-sh/setup-uv@v5
+
+    - run: uv python install "${PYTHON_VERSION}"
+      shell: bash
+      env:
+        PYTHON_VERSION: ${{ inputs.python-version }}
+
+    # A virtual environment rather than `--system`, and the reason is not only that
+    # `--system` stopped working. `ubuntu-latest`'s Debian Python is marked externally
+    # managed (PEP 668), so `uv pip install --system` is now refused outright -- which
+    # turned every job in this repository except `lint` red, with no commit to blame, and
+    # kept them red while the merges went on. The manually dispatched workflows failed
+    # the same way and more quietly still: a run that dies at its install step reports a
+    # failed tier rather than a missing one.
+    #
+    # But `--system` was the wrong instrument even while it worked: it installs into
+    # whichever interpreter `/usr` holds, *not* the one `uv python install` just placed, so
+    # the version named and the version tested were only ever the same by accident. Doing
+    # it here makes them the same by construction, which is what `ci.yml`'s matrix needs.
+    - run: |
+        uv venv --python "${PYTHON_VERSION}"
+        echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+      shell: bash
+      env:
+        PYTHON_VERSION: ${{ inputs.python-version }}
+
+    - run: uv sync --locked --extra "${EXTRA}"
+      shell: bash
+      env:
+        EXTRA: ${{ inputs.extra }}
+
+    - if: ${{ inputs.packages != '' }}
+      run: uv pip install ${PACKAGES}
+      shell: bash
+      env:
+        PACKAGES: ${{ inputs.packages }}

cleverly-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+<!-- Guides: docs/development/contributing.md and docs/development/pull-requests.md -->
+
+## What this changes
+
+<!-- The claim this change makes, and the reason for it. Name the file to read first. -->
+
+## Evidence
+
+<!-- What moved, what stayed identical, and the gate you ran. For example:
+     pytest -m "not slow": 5081 passed, 113 skipped. -->
+
+## Checks
+
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `mypy` passes
+- [ ] `pytest -m "not slow" -q` passes
+- [ ] `python -m tests.prose` findings are fixed, or carry `accepted: <reason>` in `tests/prose-report.md`
+- [ ] `nox -s docs` passes, if a document or a docstring changed
+- [ ] `python -m build`, strict Twine validation, archive checks, and clean install checks pass
+- [ ] regenerated artifacts carry matching manifest hashes and line-feed endings
+
+<!-- CI runs all of these except the prose report. Running them locally first saves a round trip,
+     and `nox -s docs` is the slowest one to learn about from a runner. -->

cleverly-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,143 @@
+name: ci
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+          extra: dev
+      - run: ruff check .
+      - run: ruff format --check .
+      # Prose is not linted here. `tests/prose.py` reports on it and the fast tier gates the
+      # *report*: a finding with no recorded judgment fails, the prose itself never does. The
+      # reason is on record -- when the dash rule was a build error, the sweep that followed
+      # optimized for green and broke six sentences to satisfy it.
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # The install steps live in the composite action; it says why they are what they are.
+      # The interpreter matches `[tool.mypy]`'s `python_version`, which is `3.12` and says at
+      # length why it is not the `3.11` of `requires-python`: numpy's stubs use PEP 695 `type`
+      # statements, which a 3.11 target refuses to parse. Running the job on the interpreter it
+      # targets keeps the two from drifting apart silently. **3.11 is still supported and still
+      # tested**. The `tests` matrix below runs the fast tier on it.
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+          extra: dev
+      - run: mypy
+
+  # The site that `pages.yml` deploys, built here before the merge rather than after it.
+  #
+  # This is not the removed documentation dispatch, and `docs/architecture-invariants.md` still
+  # rules that one out. That job re-ran what the fast tier already runs. This one covers what no
+  # fast test can see: numpydoc validation of every rendered docstring, a document that no
+  # toctree references, and a cross-reference Sphinx cannot resolve. `pages.yml` triggers on a
+  # push to `main`, so until now the first run of `-W` happened after the merge, and a broken
+  # docstring took the published site down rather than failing a pull request.
+  #
+  # 3.12 is the interpreter `pages.yml` deploys from, so this job answers the question that
+  # matters: does the site that will ship build clean. The `docs` extra is what that build needs,
+  # and this job is the one that installs it.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+          extra: docs
+      - run: sphinx-build -W --keep-going -b html docs docs/_build/html
+
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      # The matrix version is threaded through to `uv venv --python`; without that, every
+      # row of the matrix would install into `/usr`'s interpreter and exercise the same one.
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: ${{ matrix.python-version }}
+      # `-n auto` resolves through psutil, else `os.cpu_count()` -- neither of which reads a
+      # container's CFS quota, so on a quota-limited runner it asks for the *host's* cores.
+      # `tests.parallel` goes through joblib/loky, which does read it.
+      - name: Size the worker pool from the cores this job may actually use
+        run: |
+          echo "PYTEST_XDIST_AUTO_NUM_WORKERS=$(python -m tests.parallel --workers)" >> "$GITHUB_ENV"
+          python -m tests.parallel
+      # Behavioral examples belong in this fast unit/integration/e2e tier, and so do the
+      # static documentation checks -- links resolve, every `python` fence parses. Neither
+      # executes an example, and both are cheap, so there is no documentation dispatch.
+      - run: pytest -m "not slow" -q -n auto
+
+  # One backend at a time, which the `tests` job above cannot check: it installs `.[dev]`,
+  # which pulls pandas *and* polars, so the single-backend and neither-installed branches of
+  # `cleverly.utils.frames` had never executed anywhere. That is how `make_longitudinal_weighted`
+  # came to hard-code `backend="pandas"` and call `.loc` -- unusable on a polars-only install,
+  # and invisible to a suite that always had both.
+  #
+  # The test suite itself imports pandas and polars freely, so it cannot be the check here.
+  # What runs instead is the import and a fit end to end through the one backend present.
+  minimal-install:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        backend: [pandas, polars]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.11"
+          extra: ${{ matrix.backend }}
+      - name: A fit, its reports and the generators, on one backend
+        run: python scripts/smoke_backend.py ${{ matrix.backend }}
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+          extra: dev
+      - name: Build the wheel and source distribution
+        run: python -m build
+      - name: Validate package metadata and archive contents
+        run: |
+          python -m twine check --strict dist/*
+          python scripts/check_distribution.py dist
+      - name: Install and exercise the wheel in a clean environment
+        run: |
+          uv venv --python 3.12 /tmp/cleverly-wheel
+          uv pip install --python /tmp/cleverly-wheel/bin/python pandas "$(find dist -name '*.whl')"
+          /tmp/cleverly-wheel/bin/python scripts/smoke_backend.py pandas
+      - name: Install and exercise the source distribution in a clean environment
+        run: |
+          uv venv --python 3.12 /tmp/cleverly-source
+          uv pip install --python /tmp/cleverly-source/bin/python polars "$(find dist -name '*.tar.gz')"
+          /tmp/cleverly-source/bin/python scripts/smoke_backend.py polars
+      - uses: actions/upload-artifact@v5
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error

cleverly-0.1.0/.github/workflows/pages.yml

@@ -0,0 +1,45 @@
+name: pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Install documentation dependencies
+        run: uv sync --locked --extra docs
+      - name: Build documentation
+        run: uv run --no-sync sphinx-build -W --keep-going -b html docs docs/_build/html
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

cleverly-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: publish
+
+on:
+  push:
+    tags: ["v0.1.*"]
+
+permissions: {}
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Match the tag, package version, and reviewed main history
+        run: |
+          python scripts/check_release.py "$GITHUB_REF_NAME"
+          git fetch --no-tags origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main
+
+  build:
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+          extra: dev
+      - run: python -m build
+      - run: python -m twine check --strict dist/*
+      - run: python scripts/check_distribution.py dist
+      - uses: actions/upload-artifact@v5
+        with:
+          name: release-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/cleverly
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: release-distributions
+          path: dist/
+      # pypa/gh-action-pypi-publish v1.14.2 from the official upstream repository.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cleverly
+    permissions:
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v6
+        with:
+          name: release-distributions
+          path: dist/
+      # pypa/gh-action-pypi-publish v1.14.2 from the official upstream repository.
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33

cleverly-0.1.0/.github/workflows/validation.yml

@@ -0,0 +1,39 @@
+name: manual-validation
+
+# Statistical validation only. Documentation has no dispatch of its own on purpose: the
+# links and example-syntax checks are ordinary fast-tier tests and the markdown formatter
+# runs in `ci.yml`'s lint job, so a documentation suite here would re-run checks that
+# already run unconditionally -- which reads as a separate gate while adding no coverage.
+on:
+  workflow_dispatch:
+    inputs:
+      selection:
+        description: Optional pytest node id; the whole evidence re-execution tier when empty
+        type: string
+        default: ""
+
+permissions:
+  contents: read
+
+jobs:
+  validation:
+    runs-on: ubuntu-latest
+    timeout-minutes: 360
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup-env
+        with:
+          python-version: "3.12"
+      - name: Size the worker pool from the cores this job may actually use
+        run: |
+          echo "PYTEST_XDIST_AUTO_NUM_WORKERS=$(python -m tests.parallel --workers)" >> "$GITHUB_ENV"
+          python -m tests.parallel
+      - name: Statistical validation
+        env:
+          SELECTION: ${{ inputs.selection }}
+        run: |
+          if [ -n "$SELECTION" ]; then
+            pytest "$SELECTION" -q -n auto --durations=20
+          else
+            pytest -m slow -q -n auto --durations=20
+          fi

cleverly-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.nox/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.claude/
+htmlcov/
+target/
+docs/_build/
+docs/api/generated/
+
+# Where every canonical study's README sends a disposable regeneration.
+.tmp/

cleverly-0.1.0/AGENTS.md

@@ -0,0 +1,3 @@
+# Repository instructions
+
+Read and follow [`CLAUDE.md`](CLAUDE.md) for all repository-specific working agreements.

cleverly-0.1.0/CLAUDE.md

@@ -0,0 +1,113 @@
+# Working on cleverly
+
+`cleverly` is alpha software under heavy development. Treat the current architecture as
+provisional: inspect the code and tests before changing it, and do not preserve an implementation
+shape solely because this file once described it.
+
+This file holds only the working agreements that no other file states and no test enforces.
+Everything else is routed:
+
+| for | read |
+| --- | --- |
+| setup, development commands, the public overview | `README.md` |
+| making a change, and the checks it needs | `docs/development/contributing.md` |
+| opening a pull request, and the commit style | `docs/development/pull-requests.md` |
+| where technical documentation lives | `docs/README.md` |
+| cross-module constraints not derivable from one implementation | `docs/architecture-invariants.md` |
+| test tiers, and which deprecated studies no longer run | `docs/development/testing-strategy.md` |
+| designing and registering a validation study | `docs/development/method-benchmarking.md` |
+| which instrument covers which estimand | `docs/technical-reference/evidence.md` |
+| what each shipped method was validated against | `docs/technical-reference/index.md` |
+
+Current behavior is determined by code and tests, not by historical plans or investigation notes.
+
+## Scientific changes
+
+- Exact-law checks are blind to terms that vanish at the truth. When a sign, mask, guard, or
+  counterfactual block can disappear, add a nonzero witness or a deliberate-mutation control that
+  fails when that component is wrong.
+- Refuse unsupported but well-posed compositions explicitly and explain what is missing. Do not
+  silently return a convenient approximation to a different estimand.
+
+## Tests and tooling
+
+- Read `docs/development/testing-strategy.md` before choosing a tier. The fast tier is the default
+  handoff gate. The repeated-sampling studies that predate the registered rows are deprecated
+  and skipped; do not re-enable one to justify a change. A shipped method is validated by its rows
+  in the implementation validation grid, which the fast tier recomputes from committed artifacts.
+  Nothing is contingent on `pytest -m slow` running.
+- A refactor is not a reason to regenerate a study. The Python module hashes in a study's
+  `manifest.json` record the run; no test gates them, so cleaning shared code under
+  `tests/studies/evidence/` is free. The container and R-runner hashes *are* gated. Declare a
+  result-neutral edit in `tests/canonical/provenance-revisions.md` rather than rewriting a
+  recorded hash, which would leave the manifest describing bytes that never ran.
+  `docs/development/method-benchmarking.md` says how to tell the two kinds of change apart.
+- Ruff and mypy are pinned once in `pyproject.toml`'s `dev` extra, which resolves to
+  `cleverly[all]` plus tooling. An optional extra kept out of `dev` *and* out of a dedicated CI job
+  is installed by no session, so its tests can only skip, and a skipped correctness check reads
+  exactly like a passing one. Put a new extra in `dev`, or give it a job that installs and runs its
+  tests.
+- Ruff *formats* the Python examples in Markdown, so run it over the whole tree. Its linter does
+  not read Markdown at all, and the formatter skips any block it cannot parse. Neither one sees a
+  syntax error in an example.
+- Follow `docs/development/pull-requests.md` when you prepare a handoff. It gives the commit
+  subject and body style, the evidence line the body carries, and what each CI job checks. The
+  `docs` job builds the site with `-W` on every pull request, so a docstring that numpydoc rejects
+  now fails the request rather than the deploy. Run `nox -s docs` before you hand off.
+
+## Documentation writing
+
+The root `README.md` and reader-facing documents under `docs/` align with Issue 9 of
+ASD-STE100 Simplified Technical English. This project does not claim certified compliance.
+
+- Write one idea per sentence. Keep sentences to 20 words in procedures and 25 in descriptions.
+- Keep paragraphs to six sentences. Prefer three.
+- Use the active voice, the present tense, and a named actor.
+- Give the instruction first and the reason second.
+- Use one word for one meaning, and do not use the same word as two parts of speech.
+- Keep articles. Do not build a noun cluster longer than three words.
+- Do not join clauses with an em dash or `--`. Use a full stop, or a table.
+- When the content is parallel, write a table. In the technical reference the table is the primary
+  communication device and the prose exists to define its terms.
+- Statistical terms of art are exempt from the vocabulary restriction: influence curve, nuisance,
+  targeting, remainder, estimand names, and any API identifier.
+- Give evidence for each material claim. Cite the source, name the test or artifact, or state the
+  applicable condition. Remove adjectives and transitions that add no verifiable information.
+
+When you change a reader-facing document, run `python -m tests.prose`, review every finding it
+reports, and plan a fix that keeps the sentence whole. Where the standard should not apply, record
+`accepted: <reason>` against that finding in `tests/prose-report.md`; that is a passing outcome and
+the reason is the point. The fast tier fails on a finding nobody has judged, never on the prose
+itself, because a mechanical edit that satisfies a rule and breaks a sentence is the failure this
+report exists to prevent. No tool here certifies STE compliance or verifies a scientific claim.
+Check those against the code, tests, artifacts, and sources.
+
+Scope is `README.md` and every reader-facing Markdown, RST, or notebook source under `docs/`.
+Generated API pages and `docs/_build/` are not source. Rewrite the text a change touches. Do not
+sweep unrelated pages unless the user requests a broad documentation review.
+
+## Docstrings
+
+Docstrings are numpydoc, and `sphinx.ext.napoleon` is not installed. The loose `name:` form that
+napoleon accepted is now a build error, because `pages.yml` builds with `-W` and `docs/conf.py`
+enables `GL06, GL07, PR01, PR02, PR04, PR10, RT01`. Write `name : type` always, one entry per
+parameter. Two names on one line become one parameter with a comma in its name.
+
+- Document a frozen dataclass's fields under `Parameters`. numpydoc reads the generated signature,
+  so a field described only under `Attributes` reads as undocumented. Reserve `Attributes` for
+  derived properties.
+- Give a property-backed attribute its name and type and no description. numpydoc renders the
+  property's own docstring over anything written there.
+- Where a synthetic signature produces a finding nobody can fix, use the inline
+  `# numpydoc ignore=PR01` form on the definition line. Do not use `numpydoc_validation_exclude`,
+  which drops the object from every check rather than one.
+- `Examples` and `See Also` are required on the task spine only, which
+  `tests/unit/test_documentation_api.py:EXAMPLE_TARGETS` declares. The targets include core
+  methods so a direct method anchor explains its own call. Every See Also entry carries a
+  description.
+- Show the smallest normal use of the documented object or method. Start with the common case.
+  Include every import, use compact data, and check deterministic output. Do not use an example
+  to assert a statistical guarantee from one sample.
+- An example must run in the fast tier without `doctest.SKIP`. Pass explicit learners to fits;
+  the default learner library costs 30 to 120 seconds per fit. Put expensive studies and extended
+  comparisons in narrative documentation and test them separately.

cleverly-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to cleverly
+
+`cleverly` is alpha software for causal studies built on targeted maximum likelihood estimation.
+One person maintains it, so a review can take several days. Open an issue before you start a large
+change.
+
+The full guides live in the documentation site.
+
+| for | read |
+| --- | --- |
+| setup, branch names, the checks, documentation and docstring rules | [Contributing](https://esbraun.github.io/cleverly-tmle/development/contributing.html) |
+| the commit style, the pull request body, what CI does and does not check | [Pull requests](https://esbraun.github.io/cleverly-tmle/development/pull-requests.html) |
+| alpha versions, package checks, tags, and Trusted Publishing | [Releases](https://esbraun.github.io/cleverly-tmle/development/releases.html) |
+| which tier a change has to satisfy | [Test tiers and gates](https://esbraun.github.io/cleverly-tmle/development/testing-strategy.html) |
+| designing and registering a validation study | [Method benchmarking strategy](https://esbraun.github.io/cleverly-tmle/development/method-benchmarking.html) |
+
+The sources are `docs/development/contributing.md` and `docs/development/pull-requests.md`.
+
+## Set up
+
+```bash
+git clone https://github.com/esbraun/cleverly-tmle.git
+cd cleverly-tmle
+uv venv
+uv pip install -e ".[dev,docs]"
+```
+
+## Run the checks
+
+```bash
+ruff check .
+ruff format --check .
+python -m tests.prose
+mypy
+pytest -m "not slow" -q
+sphinx-build -W --keep-going -b html docs docs/_build/html
+```
+
+`nox` with no argument runs the `lint`, `typecheck`, `docs`, and `tests` sessions, which mirror the
+CI jobs. `nox -s docs` runs the last command in an isolated environment, which is what CI uses. Run
+one test tier at a time, because each tier expects the whole machine.
+
+`python -m tests.prose` reports on the reader-facing prose. It changes nothing and it fails
+nothing. Fix each finding, or record `accepted: <reason>` against it in `tests/prose-report.md`.
+The fast tier fails only on a finding with no recorded judgment.
+
+## Working agreements
+
+`CLAUDE.md` holds the working agreements that no other file states and no test enforces. Read it
+before you change scientific code, documentation prose, or a docstring.
+
+## License
+
+`cleverly` is under the [MIT License](LICENSE). Your contribution to the project is licensed
+under the same terms.
+
+One directory differs. `tests/canonical/` is under the
+[GNU General Public License v3.0](tests/canonical/LICENSE), because its R runners call
+reference packages in the same process. A contribution to that directory is licensed under
+the GPL. No published distribution carries it.

cleverly-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Braun
+
+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.