From 773908afb781bf537f408ded03582eb8678010b0 Mon Sep 17 00:00:00 2001 From: Uriah Finkel Date: Wed, 26 Aug 2026 07:36:12 +0300 Subject: [PATCH] Document persistent repository operating rules --- AGENTS.md | 199 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 120 insertions(+), 79 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 989c8ec0..60e010c9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,118 +1,159 @@ -# rtichoke Agent Information +# rtichoke Python repository rules -This document provides guidance for AI agents working on the `rtichoke` repository. +## Role and ownership + +This repository owns the Python implementation of rtichoke: Python statistical +calculations and public APIs, performance-data preparation, evaluation and +population metadata, canonical visualization adapters, immutable +`rtichoke_viz` vendoring, browser-renderer consumer adoption, and Python tests, +typing, linting, packaging, and documentation. -## Development Environment +It does not own shared TypeScript visualization contracts or renderers. -To set up the development environment, follow these steps: +## Start from fresh state -1. **Install `uv`**. -2. **Create a virtual environment** with `uv venv`. -3. **Install development dependencies** with: +Before modifying anything: - ```bash - uv sync --dev - ``` +1. Inspect actual current `main`, relevant open PRs, recent relevant merges, and + tags or releases when relevant. +2. Check whether equivalent work already exists. +3. Inspect the repository's current scripts, tests, workflows, and conventions + instead of relying on remembered commands or architecture. -## Running Tests +If actual repository state materially contradicts the task assumptions, stop +before broadening scope and report the discrepancy. -Run the test suite with: +## Scope discipline -```bash -uv run pytest -``` +Make the smallest change required. During focused work, do not opportunistically +redesign unrelated APIs, change statistics outside scope, modify +`rtichoke_viz` source, expand summary-report behavior, introduce unrelated +dependencies, or perform broad refactoring. Stop and report when a task requires +a materially broader architectural or statistical decision. -## Coding Conventions +Preserve existing public APIs and defaults unless explicitly requested. Static +behavior must remain unchanged when adding time-dependent browser adoption. Do +not add R-like APIs merely for cross-language symmetry, or add dependencies or +breaking behavior without explicit scope. -### Functional Programming +## Python conventions -Strive to use a functional programming style as much as possible. Avoid side effects and mutable state where practical. +- Prefer Polars for production dataframe work and `uv` for environment and + dependency workflows. +- Prefer existing project patterns over new abstractions and a functional style + where practical. +- Do not introduce pandas as a direct production dependency unless the task + explicitly requires it. +- Give exported functions accurate NumPy-style docstrings. +- Keep Ruff formatting and linting and `ty` type checking green. -### Docstrings +## Statistical boundary -All exported functions must have NumPy-style docstrings. Great Docs parses these docstrings to generate the API reference, so parameter, return-value, and usage documentation should remain accurate and user-facing. +Existing production statistical calculations are authoritative unless a task +explicitly targets a statistical bug or methodology change. Browser and +canonical-visualization adoption must consume already-computed production +quantities rather than recomputing statistics in adapters. -Example: +Do not change censoring logic, Aalen-Johansen logic, competing-risk handling, or +cutoff semantics unless explicitly requested. Preserve established static and +time-dependent cutoff behavior where they intentionally differ. -```python -def my_function(param1, param2): - """Summary of the function's purpose. +## Evaluation and reference identity - Parameters - ---------- - param1 : int - Description of the first parameter. - param2 : str - Description of the second parameter. +Preserve semantic identity: - Returns - ------- - bool - Description of the return value. - """ - return True -``` +- Evaluation identity represents the semantic model/population evaluation. +- Rendered-series geometry identity is distinct from evaluation identity. +- Horizon is evaluation-context and geometry metadata, not a replacement for + evaluation identity. +- Reuse `_EvaluationMetadata` and related semantic infrastructure where + appropriate. +- Never infer population identity from numerical equality. Distinct populations + remain distinct even when prevalence, event risk, or reference geometry is + numerically equal. -## Pre-commit Hooks +Use explicit semantic reference ownership. Scope population-dependent references +by semantic population, and by `population × horizon` for time-dependent outputs +when required. Multiple models sharing one population must share the same +population-owned reference where semantics require it. Do not derive ownership +from equal or unequal numeric values. -This repository uses pre-commit hooks for code quality and consistency, including `ruff-check`, `ruff-format`, and `uv-lock`. +## Canonical visualization and renderers -Run them manually with: +Canonical adapters map already-computed Python output into the shared contract. +They must preserve semantic evaluation identity and reference ownership, create +deterministic series geometry identity, carry horizon metadata where applicable, +and avoid statistical recomputation. Extend the existing adapter architecture +instead of creating parallel one-off implementations. -```bash -pre-commit run --all-files -``` +Plotly remains the default renderer unless a task explicitly changes public +defaults. Canonical browser rendering remains opt-in unless explicitly changed. +Reuse the established public renderer vocabulary and `RtichokeBrowserChart` +infrastructure. Never silently change default output types. + +## Immutable `rtichoke_viz` consumption -## Documentation +Never consume `rtichoke_viz/main`; use only immutable, verified releases and the +repository's established vendoring mechanism. Before vendoring a release, +verify all of the following: -Documentation is built with Great Docs and Quarto. +- tag and exact source commit; +- archive filename and SHA-256 against the published checksum; +- `MANIFEST` version and source commit; +- required packaged JavaScript, CSS, and schema files; +- required public renderer exports. -- Great Docs configuration: `great-docs.yml` -- Narrative guides: `user_guide/` -- Documentation dependencies: the `docs` dependency group in `pyproject.toml` -- Local build: `uv sync --group docs` followed by `uv run great-docs build` -- Pull requests receive a rendered preview under the repository's GitHub Pages site. -- Merges to `main` publish the production documentation automatically. +Never manually edit vendored renderer bytes. On upgrade, search the whole +repository for stale version, tag, archive, and checksum pins, then synchronize +all provenance records, tests, packaging assertions, and workflow guards. -Great Docs requires Python 3.11 or newer for documentation builds. This does not change the package's Python >=3.9 runtime support. +## Validation -## Type Checking +Before opening a PR, inspect the actual current scripts and workflows, run +focused tests and the complete relevant validation suite, and do not weaken +tests merely to make CI green. Run real-browser acceptance when browser rendering +changes, and packaging and provenance guards when vendored assets change. -This project uses `ty` for type checking. Run: +Current baseline commands include: ```bash -uv run ty check src tests +uv sync --all-extras --dev +uv run ruff check . +uv run ruff format --check . +uv run ty check src/rtichoke +uv run pytest tests ``` -## PR completion protocol - -Do not consider an implementation task complete merely because code has been pushed or a pull request has been opened. +Use the repository's actual current commands when they differ or when more +focused validation is appropriate. -After creating or updating a pull request: +## PR and release ownership -1. Inspect all required GitHub Actions checks for the current PR head. -2. If checks are still running, re-check them while the session is active rather than handing the PR back to the user for manual monitoring. -3. If a required check fails, inspect the failing job and logs and determine whether the failure is caused by the PR. -4. If the fix is within the stated task scope, make the fix, push it, and inspect CI again. -5. Repeat the diagnose/fix/re-check loop until all required checks pass or a genuine blocker requires user input. +For mutation tasks: -Escalate to the user only when resolving the failure would require one or more of the following: +1. Implement the focused change and validate it locally. +2. Open one focused PR. +3. Inspect GitHub Actions for the current PR head and, while the session is + active, recheck jobs that are still running. +4. Inspect failed job logs, fix in-scope failures, push, and repeat until green + or genuinely blocked. -- changing frozen statistical semantics, contracts, or architecture; -- broadening the agreed task scope; -- weakening or removing a meaningful test or quality gate; -- changing a public API or backward-compatibility promise beyond the task; -- making a product or technical decision with multiple legitimate choices; -- resolving an external service, permissions, infrastructure, or credential problem that the agent cannot fix safely. +Do not ask the user to manually check CI. Escalate only when resolution requires +a broader semantic, statistical, compatibility, dependency, product, or +infrastructure decision. Do not merge unless explicitly instructed. -Routine failures such as lint errors, formatting errors, test regressions caused by the PR, snapshots/fixtures that legitimately need updating, packaging errors, documentation-build errors, and similar mechanical issues should be fixed without asking the user to manually inspect GitHub Actions. +Do not publish Python package releases unless explicitly requested. Consumer +adoption normally stops at an unmerged focused PR. -The final handoff should include: +## Completion report -- pull request link; -- final PR head commit; -- tests/checks run locally when applicable; -- final GitHub Actions status; -- any remaining caveats or blockers. +At the end of mutation work, report: -Do not ask the user to manually check whether CI passed. +- starting `main`, final branch and head, and package version; +- files changed; +- statistical behavior changed or explicitly unchanged; +- canonical identity and reference behavior; +- vendored visualization provenance when applicable; +- local validation and final CI status; +- PR number, link, and state; +- anything deliberately deferred.