treegraphduals 0.1.0__tar.gz → 0.2.0__tar.gz

{treegraphduals-0.1.0 → treegraphduals-0.2.0}/.gitignore

@@ -16,4 +16,8 @@ dist/
 .ruff_cache/
 .env
 docs/coverage_report.md
-docs/test_results.txt
+docs/test_results.txt
+.claude/worktrees/
+DEVNOTES.md
+docs/ai_stats.md
+mutants/

treegraphduals-0.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## \[0.2.0\] - 2026-10-11
+
+### Added
+
+- Community health files: a Code of Conduct (Contributor Covenant v2.1), issue forms for bug reports, feature requests and math/definition questions, a pull request template, `SECURITY.md` and `SUPPORT.md`. Questions go to GitHub Discussions (#70).
+- Contributing guide: the contribution process, requirements for code, and the test policy (#70, #83).
+- README and docs badges, and weekly Dependabot updates for GitHub Actions and `uv.lock` (#60).
+- A quarterly SPEC 0 workflow that opens a PR raising the Python and dependency floors, and `scripts/sync_python_versions.py`, which keeps every copy of the supported-Python list in sync with `pyproject.toml` (#78).
+- AI-use disclosure: every agent-authored PR records the models, session, AI-generated files, human input and review rounds, and `CLAUDE.md` sets the provenance rules (#82).
+- AI provenance tracking: each PR's human steering and AI/human line authorship is recorded, and the totals, plus a nightly mutation-testing score, are published on the "AI Provenance" docs page (#81, ADR 0006).
+- Docs page: "How This Project Is Built with AI" (#72).
+- Agent workflow tooling: the `/work-issue` skill, a `reviewer` subagent based on Matt Pocock's skills, and a hook that keeps pushes to `main`, PR merges and repository-settings changes with the maintainer, with a test suite for the hook (#71).
+- Architecture decision records in `docs/adr/` (ADRs 0001–0006), and `.github/CODEOWNERS`.
+
+### Changed
+
+- **Breaking:** requires Python 3.13 or newer, and raises the minimum versions of NumPy (2.3), SciPy (1.15), Matplotlib (3.11), NetworkX (3.5), igraph (1.0) and SymPy (1.14), following the SPEC 0 support policy (ADRs 0001 and 0002). Python 3.12 users should stay on 0.1.0.
+- CI tests Python 3.13 and 3.14 (required) and 3.15 (non-blocking), plus a non-blocking job on the minimum dependency versions. Free-threaded builds are not tested yet, because igraph has no free-threaded wheels (ADR 0003).
+- Read the Docs builds run the test suite once. Failing tests no longer abort the docs build; the Testing page shows the failures instead (ADR 0004).
+
+### Removed
+
+- The empty `treegraphduals.agents` subpackage (planned LangGraph tooling, now out of scope) (#74).
+
+### Security
+
+- Every GitHub Action is pinned to a full commit SHA. Workflows that don't push no longer keep checkout credentials, and the release workflow defaults to a read-only token (#83).
+- An OpenSSF Scorecard workflow and README badge, and zizmor checks of the workflow files in pre-commit (#83).
+- GitHub releases carry Sigstore-signed build provenance; the docs explain how to verify it (#83).
+- Dependabot version updates wait out a 7-day cooldown; security updates are not delayed (#83).
+- Vulnerabilities are reported privately (see `SECURITY.md`), and fixes ship in the latest release only (ADR 0005).
+
+## \[0.1.0\] - 2026-09-18
+
+### Added
+
+- Initial project setup: `uv` packaging, Ruff lint/format, Pyrefly type checking, pytest + Hypothesis + coverage, Sphinx docs on Read the Docs, `CITATION.cff` with Zenodo DOI, pre-commit hooks.
+- Packaging: Hatchling build backend, so the project can be built and published (`uv build`). Ships `py.typed`, the MIT license file, README as the long description, classifiers, keywords and project URLs.
+- `tests/test_timeseries.py`: regression tests for the extrema cases below, the numerical fallback path, uniform sampling, and level-set tree construction.
+
+### Changed
+
+- **Breaking:** moved `core`, `timeseries`, `visualizations` and `agents` under a single `src/treegraphduals/` package. Imports are now `from treegraphduals.core import Tree` rather than `from core import Tree`, so the library no longer claims generic top-level names.
+- `requires-python` raised to `>=3.12`, matching what CI and Read the Docs test.
+- Test and documentation tooling moved out of runtime dependencies into the `dev` and `docs` dependency groups; a plain `pip install treegraphduals` no longer pulls in pytest and Sphinx.
+- Doctests now run by default: `testpaths` covers `src` as well as `tests`, so the `--doctest-modules` flag in CI is no longer a no-op (62 tests, up from 40).
+- `docs/conf.py` reads the version from package metadata instead of hardcoding it, and no longer injects an absolute local path for doctest setup.
+- Replaced a `print` with `warnings.warn` when symbolic differentiation falls back to the numerical extrema search.
+- Cleared the Ruff backlog (56 findings): added missing module and magic-method docstrings, made ASCII-art docstrings raw so the diagrams render literally, replaced implicit `Optional` annotations, narrowed a bare `except`, collapsed nested conditionals, sorted `__all__` lists, and dropped dead locals.
+- README reorganized into what the package computes today versus what is planned. Every original bullet is preserved; the previous single list mixed 25+ unimplemented features (duals, visibility graphs, merge trees, graph metrics) with the 7 that work, and it is the PyPI long description.
+
+### Fixed
+
+- Docstring tree diagrams rendered mangled: 15 docstrings were not raw strings, so a trailing `\` in the ASCII art silently swallowed the following newline and joined rows together (`/ \` + `1   2` became `/             1   2`). The art in the source was correct all along. Diagrams are now raw strings inside RST literal blocks, and the Horton pruning and Horton-Strahler examples are redrawn from what the algorithms actually produce.
+- The Sphinx build is now warning-free (was 84 warnings).
+- Symbolic extrema search (`TimeSeries.from_function(..., preserve_extrema=True)`) no longer silently discards critical points:
+  - Real roots that sympy returns in complex form (Cardano's formula writes the three real roots of a cubic using `I`) were dropped, because the reality test was "does `float()` succeed". Reality is now decided by the magnitude of the imaginary part, so e.g. `t**4/4 - 2*t**2 + t/3` reports its three extrema instead of none.
+  - Periodic derivatives only ever produced sympy's principal solutions, so `sin(t)` on `[0, 10]` lost its maximum at `5*pi/2`. Critical points are now solved over the interval, which enumerates the periodic solutions.
+- `plot_tree_and_harris_path` no longer leaks one matplotlib figure per call (pyplot kept every discarded `plot_tree` figure alive), and now draws the tree into its left axes instead of a "Tree plot" placeholder.

{treegraphduals-0.1.0 → treegraphduals-0.2.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use this software in your work, please cite it as below."
 title: "treegraphduals"
-version: "0.1.0"
-date-released: "2026-09-19"
+version: "0.2.0"
+date-released: "2026-10-12"
 authors:
   - family-names: "Khan"
     given-names: "Ibraheem"

{treegraphduals-0.1.0 → treegraphduals-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: treegraphduals
-Version: 0.1.0
+Version: 0.2.0
 Summary: Trees, their duals, graphs, and time series: level-set trees, Harris paths, Horton-Strahler pruning, and horizontal tunnelability graphs.
 Project-URL: Homepage, https://github.com/pikhan/treegraphduals
 Project-URL: Repository, https://github.com/pikhan/treegraphduals
@@ -15,21 +15,33 @@ Keywords: duality,graphs,harris paths,horton-strahler,level-set trees,random sel
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Requires-Dist: igraph>=0.11
-Requires-Dist: matplotlib>=3.8
-Requires-Dist: networkx>=3.2
-Requires-Dist: numpy>=1.26
-Requires-Dist: scipy>=1.11
-Requires-Dist: sympy>=1.12
+Requires-Python: >=3.13
+Requires-Dist: igraph>=1.0
+Requires-Dist: matplotlib>=3.11
+Requires-Dist: networkx>=3.5
+Requires-Dist: numpy>=2.3
+Requires-Dist: scipy>=1.15
+Requires-Dist: sympy>=1.14
 Description-Content-Type: text/markdown
 
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![CI](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml/badge.svg)](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pikhan/treegraphduals/badges/coverage.json)](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PyPI](https://img.shields.io/pypi/v/treegraphduals)](https://pypi.org/project/treegraphduals/)
+[![Python versions](https://img.shields.io/pypi/pyversions/treegraphduals)](https://pypi.org/project/treegraphduals/)
+[![License](https://img.shields.io/pypi/l/treegraphduals)](https://github.com/pikhan/treegraphduals/blob/main/LICENSE)
 [![Docs](https://readthedocs.org/projects/treegraphduals/badge/?version=latest)](https://treegraphduals.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/pikhan/treegraphduals/badge)](https://scorecard.dev/viewer/?uri=github.com/pikhan/treegraphduals)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15397/badge)](https://www.bestpractices.dev/projects/15397)
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Typed: Pyrefly](https://img.shields.io/badge/typed-Pyrefly-blue)](https://pyrefly.org/)
+[![Tested with Hypothesis](https://img.shields.io/badge/tested%20with-Hypothesis-blue)](https://hypothesis.readthedocs.io/)
 
 # treegraphduals
 
@@ -46,7 +58,7 @@ the piece you need is ready.
 pip install treegraphduals     # or: uv add treegraphduals
 ```
 
-Requires Python 3.12+.
+Requires Python 3.13+.
 
 ## Quickstart
 
@@ -167,6 +179,15 @@ The graph classes are intended to become general enough to allow for:
 
 Full API documentation, tutorials, and examples: <https://treegraphduals.readthedocs.io>
 
+## Getting help and contributing
+
+- Questions: [GitHub Discussions](https://github.com/pikhan/treegraphduals/discussions) (Q&A; definition
+  questions go in Math and Definitions).
+- Bugs, feature requests and definition disagreements: [issues](https://github.com/pikhan/treegraphduals/issues/new/choose).
+- Security vulnerabilities: report privately, see [`SECURITY.md`](SECURITY.md).
+- Contributing: see the [contributing guide](https://treegraphduals.readthedocs.io/en/latest/contributing.html).
+  Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md); [`SUPPORT.md`](SUPPORT.md) has the details.
+
 ## Citing
 
 If you use this package, please cite it via the DOI above, or see

{treegraphduals-0.1.0 → treegraphduals-0.2.0}/README.md

@@ -1,5 +1,17 @@
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![CI](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml/badge.svg)](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pikhan/treegraphduals/badges/coverage.json)](https://github.com/pikhan/treegraphduals/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![PyPI](https://img.shields.io/pypi/v/treegraphduals)](https://pypi.org/project/treegraphduals/)
+[![Python versions](https://img.shields.io/pypi/pyversions/treegraphduals)](https://pypi.org/project/treegraphduals/)
+[![License](https://img.shields.io/pypi/l/treegraphduals)](https://github.com/pikhan/treegraphduals/blob/main/LICENSE)
 [![Docs](https://readthedocs.org/projects/treegraphduals/badge/?version=latest)](https://treegraphduals.readthedocs.io/en/latest/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22839827.svg)](https://doi.org/10.5281/zenodo.22839827)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/pikhan/treegraphduals/badge)](https://scorecard.dev/viewer/?uri=github.com/pikhan/treegraphduals)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/15397/badge)](https://www.bestpractices.dev/projects/15397)
+
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
+[![Typed: Pyrefly](https://img.shields.io/badge/typed-Pyrefly-blue)](https://pyrefly.org/)
+[![Tested with Hypothesis](https://img.shields.io/badge/tested%20with-Hypothesis-blue)](https://hypothesis.readthedocs.io/)
 
 # treegraphduals
 
@@ -16,7 +28,7 @@ the piece you need is ready.
 pip install treegraphduals     # or: uv add treegraphduals
 ```
 
-Requires Python 3.12+.
+Requires Python 3.13+.
 
 ## Quickstart
 
@@ -137,6 +149,15 @@ The graph classes are intended to become general enough to allow for:
 
 Full API documentation, tutorials, and examples: <https://treegraphduals.readthedocs.io>
 
+## Getting help and contributing
+
+- Questions: [GitHub Discussions](https://github.com/pikhan/treegraphduals/discussions) (Q&A; definition
+  questions go in Math and Definitions).
+- Bugs, feature requests and definition disagreements: [issues](https://github.com/pikhan/treegraphduals/issues/new/choose).
+- Security vulnerabilities: report privately, see [`SECURITY.md`](SECURITY.md).
+- Contributing: see the [contributing guide](https://treegraphduals.readthedocs.io/en/latest/contributing.html).
+  Everyone taking part follows the [Code of Conduct](CODE_OF_CONDUCT.md); [`SUPPORT.md`](SUPPORT.md) has the details.
+
 ## Citing
 
 If you use this package, please cite it via the DOI above, or see

treegraphduals-0.2.0/docs/adr/0001-spec-0-support-policy.md

@@ -0,0 +1,83 @@
+# 0001. Follow SPEC 0 for supported Python and dependency versions
+
+- **Status:** Accepted
+- **Date:** 2026-10-10
+- **Issues:** #76, #77, #78, #75, #79
+
+## Context
+
+treegraphduals is a scientific Python library. Its core dependencies (NumPy,
+SciPy, Matplotlib, NetworkX) follow [SPEC 0](https://scientific-python.org/specs/spec-0000/)
+and drop old versions on a published quarterly schedule. SPEC 0 recommends
+dropping a Python version **3 years** after its release and a core package
+version **2 years** after its release. The stated purpose is to limit
+maintenance burden. Projects may drop earlier when a critical fix isn't
+backported. SPEC 0 doesn't forbid supporting versions longer.
+
+Before this ADR, the floors (`requires-python >=3.12`, `numpy>=1.26`,
+`scipy>=1.11`, `matplotlib>=3.8`, `networkx>=3.2`) were all older than SPEC 0
+allows. CI tested none of them: it tested only the latest locked versions, on
+one interpreter. The floors were claims, not tested facts.
+
+Installers honor `Requires-Python`. When a release drops a Python version,
+users on that version keep getting the last release that supported it.
+Dropping a version never breaks existing users.
+
+JOSS and pyOpenSci reviewers (#64) look for a stated support policy.
+
+## Options considered
+
+- **A. Follow SPEC 0.** Drop each Python version 3 years after release and each
+  core-package version 2 years after release, quarterly. This is the same
+  schedule our dependencies use, and it keeps CI small.
+- **B. SPEC 0, but keep each Python version once it works ("perpetual
+  support").** The claim decays. Once NumPy and SciPy stop publishing wheels
+  for a version, CI on it tests ever-older dependencies that nobody else tests.
+  CPython itself stops security fixes 5 years after release (3.13: October 2029).
+  "It worked when we tested it" says nothing about code written later. Users
+  on old versions are already served by old releases (see Context).
+- **C. A fixed floor, bumped when someone remembers.** What the project did
+  until now. The floors drifted (see Context).
+- **D. NEP 29.** Superseded by SPEC 0.
+
+## Decision
+
+1. **Python.** Support each CPython minor version until its SPEC 0 drop date
+   (3 years after its x.y.0 release). The `requires-python` floor is the oldest
+   version still in that window. Drop earlier only if a dependency we need
+   forces it. Python 3.12 is dropped at the next release (#77), at its SPEC 0
+   date (2026 Q4), or a few days before it if that release lands before
+   2026-10-01.
+2. **Core dependencies** (the SPEC 0 core packages we depend on: NumPy, SciPy,
+   Matplotlib, NetworkX). Floors follow SPEC 0's 2-year window.
+3. **Other runtime dependencies** (igraph, SymPy, and any added later). Floors
+   follow the same 2-year window (spec0-action's `update_all: 2`). They are
+   raised further when CI's lowest-direct job (#78) shows they must be.
+4. **Cadence.** Floors are bumped quarterly by an automated PR (#78) that a
+   maintainer reviews and merges. The PR's GitHub notification (email) is the
+   maintainer's prompt to act; no separate calendar or email reminder is
+   required. A release after a quarter boundary includes that quarter's drops.
+5. **New Python versions.** As soon as uv can install a prerelease, add it and
+   its free-threaded build to CI as non-blocking jobs. Make the normal build
+   blocking, and add its classifier, once the final release is out, every
+   runtime dependency installs from wheels, and the job has been green on
+   `main` (#79 for 3.15).
+6. **Free-threaded builds** are tested in non-blocking jobs only. We don't
+   claim free-threading support (no classifier, no thread-safety guarantee)
+   until a separate ADR decides to.
+7. **Development** happens on the newest blocking version. CI's lint and
+   type-check job runs on the floor.
+8. **No upper bounds** on dependencies. `uv.lock` pins exact versions for
+   development.
+
+## Consequences
+
+- The next release requires Python 3.13+ and raises the dependency floors
+  (#77). Python 3.12 users keep getting 0.1.x.
+- Expected Python drops: 3.13 in 2027 Q4, 3.14 in 2028 Q4.
+- Every quarter an automated PR arrives. CI must pass on the new floors,
+  including the lowest-direct job.
+- The supported-version list lives in several files (pyproject, CI matrix,
+  `.readthedocs.yaml`, the release smoke test, README, CLAUDE.md). #78
+  keeps them in sync.
+- Rules out perpetual support (option B) and unscheduled floor bumps (option C).

treegraphduals-0.2.0/docs/adr/0002-spec-0-windows-per-minor-version.md

@@ -0,0 +1,46 @@
+# 0002. Count SPEC 0 dependency windows per minor version
+
+- **Status:** Proposed
+- **Date:** 2026-10-11
+- **Issues:** #77, #78
+
+## Context
+
+[ADR 0001](0001-spec-0-support-policy.md) decisions 2 and 3 set dependency
+floors by a 2-year window, but don't say what the window is counted over. Two
+readings give different floors:
+
+- **Per release:** the floor is the oldest *release* (any patch) from the last
+  2 years. In 2026 Q4 this gives `igraph>=0.11.8` (released 2024-10-28).
+- **Per minor version:** the floor is the oldest *minor version* whose x.y.0
+  release came out in the last 2 years. igraph 0.11's first release was
+  2023-10-12, so 0.11 is out and the floor is `igraph>=1.0` (2025-10-23).
+
+[SPEC 0](https://scientific-python.org/specs/spec-0000/) uses the
+per-minor-version reading: its drop schedule lists minor versions by the date of
+their x.y.0 release. spec0-action, which #78 uses to automate the quarterly
+bumps, does the same.
+
+## Options considered
+
+- **Per release.** Floors can land on a patch release. This is not what SPEC 0
+  or spec0-action computes, so the automated bumps (#78) would disagree with
+  the floors set by hand.
+- **Per minor version.** Floors move in bigger steps (igraph skips from
+  0.11.x straight to 1.0), but they match SPEC 0 and the tool that maintains
+  them.
+
+## Decision
+
+Every dependency floor under ADR 0001 decisions 2 and 3, for core and other
+runtime dependencies alike, is the oldest minor version whose x.y.0 release is
+within the 2-year window, written `>=x.y`. Floors are never set to a patch
+release. Python versions are already counted per minor version (ADR 0001
+decision 1).
+
+## Consequences
+
+- #77 sets `igraph>=1.0`, not `>=0.11.8`. SymPy is `>=1.14` under either
+  reading.
+- #78's spec0-action configuration must use this rule. Its default already does.
+- ADR 0001 is otherwise unchanged.

treegraphduals-0.2.0/docs/adr/0003-no-free-threaded-ci-jobs.md

@@ -0,0 +1,55 @@
+# 0003. Don't test free-threaded Python builds in CI for now
+
+- **Status:** Proposed
+- **Date:** 2026-10-11
+- **Issues:** #75, #79
+- **Supersedes:** decision 6, and the free-threaded part of decision 5, of
+  [ADR 0001](0001-spec-0-support-policy.md)
+
+## Context
+
+[ADR 0001](0001-spec-0-support-policy.md) decision 6 put free-threaded builds
+(3.14t, 3.15t) in non-blocking CI jobs as an early warning. #75 added those
+jobs. On their first runs (PR #88), neither job got as far as running a test:
+
+- igraph 1.0.0, a runtime dependency, publishes only limited-API (`abi3`)
+  wheels. Free-threaded CPython rejects the limited API
+  (`#error "The limited API is not currently supported in the free-threaded
+  build"`), so there is no wheel to install and the source build fails.
+- NumPy, SciPy, Matplotlib and Pillow already ship free-threaded wheels. igraph
+  is the only blocker.
+
+We can't fix this. Until igraph ships free-threaded wheels, these jobs fail at
+`uv sync` on every PR. They test none of our code, and a permanent red ✗ teaches
+everyone to ignore red marks.
+
+We don't claim free-threading support, and the ensembles in #49 parallelize just
+as well with a process pool on any Python. Nothing we ship depends on free
+threading.
+
+## Options considered
+
+- **A. Keep the jobs, non-blocking (ADR 0001 decision 6).** They give no signal
+  until igraph changes, and every PR shows red marks until then. Each new
+  free-threaded version would then repeat the wait for dependency wheels.
+- **B. Remove the jobs, and revisit once igraph ships free-threaded wheels.**
+  No noise, and no loss of signal, because the jobs test nothing today.
+- **C. Build igraph from source in CI without the limited API.** That would
+  mean maintaining a build of a C extension we don't own, for a feature we
+  don't claim.
+
+## Decision
+
+1. CI runs no free-threaded (`t`) Python builds. This supersedes ADR 0001
+   decision 6.
+2. We still claim no free-threading support: no classifier, and no
+   thread-safety guarantee.
+3. Revisit once igraph publishes free-threaded wheels (`cp3XXt`) on PyPI. Then a
+   new ADR can restore non-blocking free-threaded jobs.
+
+## Consequences
+
+- `ci.yml` drops the 3.14t and 3.15t jobs (#75).
+- #79 covers only the normal 3.15 build. 3.15t is no longer in CI.
+- ADR 0001 decision 5's "and its free-threaded build" no longer applies to new
+  Python versions.

treegraphduals-0.2.0/docs/adr/0004-docs-build-runs-tests-once-and-reports-failures.md

@@ -0,0 +1,60 @@
+# 0004. Read the Docs runs the test suite once and publishes failures
+
+- **Status:** Proposed
+- **Date:** 2026-10-11
+- **Issues:** #31
+
+## Context
+
+The Testing page (`docs/testing.rst`) includes `docs/test_results.txt` and
+`docs/coverage_report.md`, and links to the HTML coverage report. These files
+are gitignored. Read the Docs (RTD) generates them in its `pre_build` step.
+
+That step ran the suite twice. The first run aborted the build on any failure,
+so the `|| true` on the second run, which wrote `test_results.txt`, never took
+effect. The page could only ever show green, and each docs build took twice
+as long as it needed to. `pytest.ini`'s `addopts` already add coverage, the HTML
+report and doctests to every run, so one run produces everything the page needs.
+
+CI already runs the full suite, and its `test` check is required to merge into
+`main`.
+
+## Options considered
+
+- **A. Move report generation into CI, and have RTD only build Sphinx.** RTD
+  can't download GitHub Actions artifacts without a token, and those artifacts
+  expire. RTD builds start on push, often before CI finishes, so the reports
+  would lag a commit behind. Too much machinery for the real problem, which is
+  the doubled run time.
+- **B. Gate: run once, and a failing test aborts the docs build.** A build that
+  aborts leaves RTD serving the last successful build. If broken code reached
+  `main`, the docs would keep showing stale green results.
+- **C. Report: run once, and a failing test doesn't abort the build.** The docs
+  always match `main`. Normally `main` is green, because CI blocks broken
+  merges, so the page is green. If broken code gets in anyway, the page shows it.
+
+## Decision
+
+Option C, with tests that fail to load still aborting the build (maintainer,
+on #31 and in the PR #98 session):
+
+1. RTD keeps generating the test and coverage reports. They don't move to CI.
+2. `pre_build` runs pytest once. Its output goes to `docs/test_results.txt`,
+   and the coverage reports (`coverage_report.md`, `coverage.json`, `htmlcov/`)
+   come from that same run's data.
+3. Failing tests (pytest exit code 1) don't abort the docs build. The failures
+   appear on the Testing page.
+4. If the suite doesn't run properly (exit code 2 or higher: tests that fail to
+   load, no tests collected, or a pytest error), the docs build aborts. The
+   same failure already fails CI and blocks the merge. In that case RTD keeps
+   serving the last good build, rather than publishing a page with no results
+   and no coverage.
+5. CI's required `test` check, not the docs build, is the merge gate.
+
+## Consequences
+
+- `.readthedocs.yaml` writes the single pytest run to `test_results.txt`, echoes
+  it to the build log, and aborts only when pytest's exit code is 2 or higher
+  (#31).
+- A red Testing page on `main` means broken code got past CI: treat it as a bug.
+- A green docs build no longer means the tests passed. Check CI for that.

treegraphduals-0.2.0/docs/adr/0005-security-fixes-for-latest-release-only.md

@@ -0,0 +1,59 @@
+# 0005. Security fixes go into the latest release only
+
+- **Status:** Proposed
+- **Date:** 2026-10-11
+- **Issues:** #70, #76, #83
+
+## Context
+
+`SECURITY.md` (#70) has to say which versions get security fixes. GitHub shows
+the policy under the repository's Security tab, the OpenSSF Scorecard
+Security-Policy check looks for it (#83), and JOSS and pyOpenSci reviewers
+expect one (#64).
+
+Vulnerabilities are reported privately through GitHub's private vulnerability
+reporting (#83). A fix is coordinated in a GitHub security advisory and
+published with a release.
+
+The project has one maintainer, and releases are cut from `main`. There are no
+maintenance branches.
+
+[ADR 0001](0001-spec-0-support-policy.md) has the project follow SPEC 0. Each
+release drops the Python and dependency versions that have left the SPEC 0
+window. Installers honor `Requires-Python`, so users on a dropped Python keep
+getting the last release that supported it. ADR 0001 covers which versions a
+*release* supports. It doesn't say which *releases* get fixes.
+
+## Options considered
+
+- **A. Latest release only.** Fixes ship in a new release from `main`, and
+  nothing is backported. This is the least work, and it's consistent with
+  ADR 0001: old releases are for old environments, not maintained lines. Users on a Python
+  that SPEC 0 has dropped don't get the fix.
+- **B. The latest release, plus backports to the previous minor series.** This
+  needs maintenance branches, a release process for each one, and CI for
+  dependency floors that `main` no longer tests. One maintainer can't keep
+  that up.
+- **C. The last release for every Python version still supported by CPython.**
+  This is the most generous option. It brings back the old-floor maintenance
+  that ADR 0001 ruled out, and the dependencies themselves stop releasing for
+  those versions.
+
+## Decision
+
+1. Security fixes are made **only in a new release** cut from `main`. Earlier
+   releases get no fixes, and nothing is backported.
+2. That release follows ADR 0001, so it supports only the Python and
+   dependency versions in the SPEC 0 window when it is made.
+3. The advisory published with the fix names the affected versions and the
+   fixed version, so users on older releases can see that they are affected.
+4. `SECURITY.md` states this policy, and it cites this ADR.
+
+## Consequences
+
+- To get a fix, users upgrade to the latest release. A user on a Python that
+  SPEC 0 has dropped has to upgrade Python first.
+- No maintenance branches or backport process are needed.
+- Changing this policy, for example to backport to the previous minor series
+  once the project has more maintainers, takes a new ADR that supersedes this
+  one.

treegraphduals-0.2.0/docs/adr/0006-ai-provenance-tracking.md

@@ -0,0 +1,126 @@
+# 0006. AI provenance: what is tracked, how, and where it is published
+
+- **Status:** Proposed
+- **Date:** 2026-10-11
+- **Issues:** #81, #80, #72
+
+## Context
+
+JOSS and pyOpenSci both require a disclosure of AI use (#80), and the
+maintainer wants to see where human effort goes: into prompting and into code.
+Most of the evidence can't be reconstructed later. Commits carry no AI trailers,
+squash merges collapse branch history, and Claude Code deletes session
+transcripts after `cleanupPeriodDays` (30 days by default).
+
+#81 left five decisions to the maintainer. They were settled in the issue
+(the maintainer's comment of 2026-10-11, US time) and in the `/work-issue 81` session:
+
+- **(a) Tool.** git-ai would work, but the goal is to see where human effort
+  went, not attribution alone. Custom scripts only if git-ai can't do it.
+- **(b) Formal approvals.** No bot identity. Commits and PRs stay under the
+  maintainer's identity, and the maintainer reviews and merges every PR.
+- **(c) Merge strategy.** Keep squash merges. The PR process doesn't change.
+- **(d) What to publish.** Aggregates and per-PR numbers. No transcripts.
+- **(e) Retention.** The 30-day default is fine.
+
+## Options considered
+
+- **git-ai** (open source, Apache-2.0) records line-level AI authorship in git
+  notes through agent hooks. It needs a background daemon and user-level hooks
+  installed by `curl | bash`. Keeping notes through GitHub's squash merge needs a
+  CI workflow that installs git-ai the same way and pushes with a
+  `contents: write` token. That cuts against the workflow hardening of #97, and
+  git-ai doesn't measure prompting effort at all.
+- **A per-PR count from transcripts and commits.** One stdlib-only script reads
+  the transcripts for steering, decides per commit whether an agent made it,
+  and blames the PR's added lines. It needs no new tool and no write-token
+  workflow beyond the existing pattern, but gives per-PR totals, not per-line
+  blame on `main`.
+
+The maintainer chose the per-PR count.
+
+## Decision
+
+`scripts/ai_provenance.py` records, for each PR, one comment that starts with
+`<!-- ai-provenance:v1 -->` and holds a JSON record. It is computed on the
+maintainer's machine, where the transcripts are. `/work-issue` step 8 runs it,
+and a `SessionEnd` hook in `.claude/settings.json` runs it again in the
+background when a session closes.
+
+**Sessions → PRs.** A session counts for a PR if it created the PR (a `pr-link`
+record), worked on its head branch, or is named in the PR body. Within a
+session, a transcript record counts for the PR whose head branch it was on.
+Otherwise it counts for the first PR the session linked at or after it, or the
+last one if it came after all of them.
+
+**Human steering**, per PR:
+
+- *messages*: user records with `origin.kind == "human"`, excluding interrupts. A
+  slash command counts as the `/name args` that was typed.
+- *words* and *characters* of those messages, plus words typed into
+  AskUserQuestion answers. Picking an offered option counts as an *answer*, not
+  as words.
+- *active time*: for each message, the time since Claude's previous output; for
+  each answer, the time since the question. Each is capped at **15 minutes**, so
+  breaks don't count. A session's first message counts zero.
+- *wall clock*: the span of the session's records that count for the PR.
+- *messages after approval*: messages after the first reviewer hand-back with
+  verdict APPROVE.
+
+**Agents**, per PR: models, effort levels and tokens (input including cache
+reads and writes; output), deduplicated per API response, from the main and
+subagent transcripts; agent time as the length of the union of the intervals
+`[t − durationMs, t]` over the `turn_duration` records (within one prompt the
+value is sometimes cumulative and sometimes per turn, and the union is right in
+both cases); reviewer verdicts.
+
+**Line authorship.** Each commit in `merge-base..head` is *ai* if an agent's
+Bash output showed git's `[branch sha]` summary for it, or if its **author
+date** falls within one of the agents' Bash calls (±2 s). The author date
+survives rebases such as GitHub's "Update branch". Every other commit is
+*human*. Each non-blank line the PR adds is blamed over that range. A line from
+an *ai* commit is `ai`. A line from a *human* commit is `ai_edited` if that
+commit's hunk replaced lines an *ai* commit had added, and otherwise `human`.
+Lines are split into `src/`, `tests/`, `docs/` and other. The **coverage rule**
+follows: whatever no transcript shows an agent doing counts as human, so
+AI-written code must enter only through Claude Code (already a `CLAUDE.md`
+rule).
+
+Re-running keeps what an earlier run recorded: sessions whose transcripts have
+expired, and commits already classified *ai*.
+
+**Publishing.** The `Stats` workflow (on push to `main`, nightly, and on
+demand) reads every merged PR's provenance comment, plus GitHub's data: reviewer
+rounds and verdicts from the `Automated review (round N)` comments, formal
+reviews, line comments, commits, time open, and which closed `difficulty: max`
+issues human-written PRs closed. It writes `ai-stats.json` to the orphan `stats`
+branch, the same pattern as the coverage badge. A PR whose final head differs
+from the head its record was computed at is flagged `stale`. Each row also
+counts the PR's commits by class, so human commits pushed to agent PRs are
+published. Only comments by the repository owner (`authorAssociation`
+`OWNER`) are read, and a malformed record is ignored, so other people's
+comments can't forge or break the numbers. The Read the Docs
+build renders the JSON on the *AI provenance* page. Nothing from the transcripts
+is published except these numbers.
+
+**Test strength.** mutmut runs nightly in the same workflow on
+`src/treegraphduals/core` and `timeseries` (plotting code is excluded). The
+score, (killed + timeout + segfault) / (those + survived + suspicious +
+no tests), is published with the stats. Deterministic Hypothesis in CI stays
+with #51.
+
+## Consequences
+
+- Every agent PR gets a provenance comment. Human PRs without one count as
+  human when their AI use section says "None: written by a human".
+- PRs merged before this lands can be backfilled with `collect <pr>` while their
+  transcripts still exist (30 days).
+- Known gaps: a human edit that an agent commits along with its own, a human
+  amending an agent's commit, or a human commit authored while an agent's Bash
+  call (such as a long test run) was running in a session on the same PR, counts
+  as AI. Code pasted from other AI chats
+  counts as human. Effort in sessions that never touch a PR (planning, triage)
+  isn't attributed to any PR.
+- Formal approval records stay impossible (decision b). The review metrics are
+  the reviewer agent's rounds and the maintainer's messages after its approval.
+- #72's page builds on the generated statistics and this ADR.