Document persistent repository operating rules

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.