pystatistics 2.3.0__tar.gz → 3.0.1__tar.gz

pystatistics-3.0.1/.release/CHECKLIST.md

@@ -0,0 +1,84 @@
+# Release Checklist
+
+> `release.py` only automates the version bump in `pyproject.toml` and
+> `<package>/__init__.py`. Everything else is by hand — on purpose.
+> The CHANGELOG entry in particular is authorship work, not mechanical:
+> `UNRELEASED.md` is written in internal voice, `CHANGELOG.md` is public.
+
+## Release flow
+
+1. **Sanity check:** `python .release/release.py --status`
+
+2. **Write the `CHANGELOG.md` entry by hand.** Open `UNRELEASED.md` for
+   reference, then translate it into user-facing prose at the top of
+   `CHANGELOG.md` under `## X.Y.Z`. Do NOT copy verbatim. Strip:
+   - internal rule numbers (e.g. "Rule 9", "Rule 10")
+   - internal project names
+   - test counts / coverage numbers / process rationale
+   - references to `CLAUDE.md` by name or implication
+
+   Keep:
+   - API additions / removals
+   - behaviour changes a user would notice
+   - bug fixes (in terms of the user-visible symptom)
+   - performance numbers (with shape context)
+
+3. **Update `README.md` "What's New".** Same translation rules as the
+   CHANGELOG. The README should lead with library identity; the changelog
+   lives near the bottom.
+
+4. **Bump versions:** `python .release/release.py --bump X.Y.Z` — this
+   only touches `pyproject.toml` and `<package>/__init__.py`.
+
+5. **Review:** `git diff`
+
+6. **Commit and tag:**
+   ```
+   git add pyproject.toml <package>/__init__.py CHANGELOG.md README.md
+   git commit -m "Release X.Y.Z"
+   git tag vX.Y.Z
+   git push origin <branch>
+   git push origin vX.Y.Z
+   ```
+
+7. **Reset UNRELEASED.md** — only now, after the release commit is in:
+   ```
+   python .release/release.py --reset-unreleased
+   git add .release/UNRELEASED.md
+   git commit -m "Reset UNRELEASED.md for next cycle"
+   git push
+   ```
+
+8. **Publish to PyPI via GitHub release:**
+   ```
+   gh release create vX.Y.Z --title 'vX.Y.Z' --notes-file CHANGELOG.md
+   ```
+   This triggers `publish.yml` → PyPI.
+
+9. **Verify:** `pip install <package>==X.Y.Z`
+
+## Why there is no `--commit` mode
+
+A previous version of this script had a `--commit` flag that did the
+changelog prepend, the UNRELEASED reset, and the git commit/tag/push in
+one shot. Two problems:
+
+- It copied `UNRELEASED.md` verbatim into `CHANGELOG.md`. `UNRELEASED.md`
+  is written in internal developer voice; `CHANGELOG.md` is read by
+  strangers on PyPI. That's a Rule-10 audience violation, and the
+  automation made it the path of least resistance.
+- It coupled the mechanical bump with the human authorship steps, so
+  there was no natural point to review the translation before the
+  commit went out.
+
+Doing the authorship by hand, then using the script only for the literal
+version strings, is slower on paper and safer in practice.
+
+## Historical foot-guns
+
+- **v1.6.1 (2026-ish):** release commit missed unstaged source edits
+  because only tracked files were staged. Mitigation: always run
+  `git status` before `git commit` and confirm the diff contains every
+  file the release should ship.
+- **Multiple PyPI publish failures:** every one has been a missed manual
+  step from this list. Work top to bottom; do not skip.

pystatistics-3.0.1/.release/release.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""
+Release utility for pystatistics / pystatsbio.
+
+This script ONLY automates the mechanical, judgement-free parts of a
+release. Everything that needs human authorship — in particular, the
+public-facing CHANGELOG.md entry — is left to you.
+
+Why: UNRELEASED.md is written in internal developer voice (rule numbers,
+project names, test counts, development rationale). CHANGELOG.md is a
+public file read by strangers on PyPI. Copying one into the other is a
+Rule-10 violation. The translation must be done by hand.
+
+Usage:
+    python .release/release.py --status              # show version state + unreleased summary
+    python .release/release.py --check X.Y.Z         # dry-run: validate the bump
+    python .release/release.py --bump X.Y.Z          # bump pyproject.toml + __init__.py
+    python .release/release.py --reset-unreleased    # wipe UNRELEASED.md to template
+                                                       (only after CHANGELOG entry is written)
+
+What this script does:
+    --bump:
+      1. Validates new version > current version
+      2. Writes new version to pyproject.toml
+      3. Writes new version to <package>/__init__.py
+
+    --reset-unreleased:
+      1. Overwrites UNRELEASED.md with the empty template
+
+What this script does NOT do (you must do these yourself):
+    - Write the CHANGELOG.md entry. Translate UNRELEASED.md into
+      user-facing prose by hand. Do not copy verbatim.
+    - Update the README "What's New" section.
+    - git add / commit / tag / push.
+    - gh release create.
+
+Typical flow:
+    1. `--status`                                       (sanity check)
+    2. Write the CHANGELOG.md entry by hand.            (translation)
+    3. Update README.md "What's New" by hand.           (translation)
+    4. `--bump X.Y.Z`                                   (mechanical)
+    5. `git diff`                                       (review)
+    6. git add / commit / tag / push                    (manual)
+    7. `--reset-unreleased`                             (only after commit)
+    8. Commit the reset, then `gh release create`.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import textwrap
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+RELEASE_DIR = REPO_ROOT / ".release"
+UNRELEASED_PATH = RELEASE_DIR / "UNRELEASED.md"
+
+
+# ---------------------------------------------------------------------------
+# Discovery
+# ---------------------------------------------------------------------------
+
+def find_package() -> str:
+    """Find the Python package directory (has __init__.py with __version__)."""
+    for d in sorted(REPO_ROOT.iterdir()):
+        if d.is_dir() and (d / "__init__.py").exists():
+            init_text = (d / "__init__.py").read_text()
+            if "__version__" in init_text:
+                return d.name
+    raise FileNotFoundError("Cannot find package with __version__ in __init__.py")
+
+
+def get_current_version() -> str:
+    toml = (REPO_ROOT / "pyproject.toml").read_text()
+    m = re.search(r'^version\s*=\s*"([^"]+)"', toml, re.MULTILINE)
+    if not m:
+        raise ValueError("Cannot find version in pyproject.toml")
+    return m.group(1)
+
+
+def get_init_version(package: str) -> str:
+    init = (REPO_ROOT / package / "__init__.py").read_text()
+    m = re.search(r'__version__\s*=\s*"([^"]+)"', init)
+    if not m:
+        raise ValueError(f"Cannot find __version__ in {package}/__init__.py")
+    return m.group(1)
+
+
+def get_changelog_version() -> str | None:
+    changelog = REPO_ROOT / "CHANGELOG.md"
+    if not changelog.exists():
+        return None
+    text = changelog.read_text()
+    m = re.search(r'^## (\d+\.\d+\.\d+)', text, re.MULTILINE)
+    return m.group(1) if m else None
+
+
+# ---------------------------------------------------------------------------
+# UNRELEASED.md
+# ---------------------------------------------------------------------------
+
+EMPTY_UNRELEASED = textwrap.dedent("""\
+    # Unreleased Changes
+
+    > This file tracks all changes since the last stable release.
+    > Updated by whoever makes a change, on whatever machine.
+    > Synced via git so all sessions (Mac, Linux, etc.) see the same state.
+    >
+    > When ready to release, run: `python .release/release.py --status`
+    > and follow the manual release flow in the script docstring.
+
+    ## Changes
+
+    *(empty — no unreleased changes yet)*
+""")
+
+
+def get_unreleased_content() -> str:
+    if not UNRELEASED_PATH.exists():
+        return ""
+    text = UNRELEASED_PATH.read_text()
+    m = re.search(r'^## Changes\s*\n(.*)\Z', text, re.MULTILINE | re.DOTALL)
+    if not m:
+        return ""
+    content = m.group(1).strip()
+    if not content or content == "*(empty — no unreleased changes yet)*":
+        return ""
+    return content
+
+
+def reset_unreleased() -> None:
+    UNRELEASED_PATH.write_text(EMPTY_UNRELEASED)
+
+
+# ---------------------------------------------------------------------------
+# Version bumping
+# ---------------------------------------------------------------------------
+
+def bump_pyproject(new_version: str) -> None:
+    path = REPO_ROOT / "pyproject.toml"
+    text = path.read_text()
+    text = re.sub(
+        r'^(version\s*=\s*)"[^"]+"',
+        rf'\g<1>"{new_version}"',
+        text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    path.write_text(text)
+
+
+def bump_init(package: str, new_version: str) -> None:
+    path = REPO_ROOT / package / "__init__.py"
+    text = path.read_text()
+    text = re.sub(
+        r'(__version__\s*=\s*)"[^"]+"',
+        rf'\g<1>"{new_version}"',
+        text,
+        count=1,
+    )
+    path.write_text(text)
+
+
+def parse_version(v: str) -> tuple[int, ...]:
+    return tuple(int(x) for x in v.split("."))
+
+
+def validate_version(new: str, current: str) -> None:
+    try:
+        new_t = parse_version(new)
+        cur_t = parse_version(current)
+    except (ValueError, AttributeError) as e:
+        raise ValueError(f"Invalid version format: {e}") from e
+
+    if new_t <= cur_t:
+        raise ValueError(
+            f"New version {new} must be greater than current {current}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_status() -> None:
+    package = find_package()
+    v_toml = get_current_version()
+    v_init = get_init_version(package)
+    v_log = get_changelog_version()
+    unreleased = get_unreleased_content()
+
+    print(f"Package:      {package}")
+    print(f"pyproject:    {v_toml}")
+    print(f"__init__:     {v_init}")
+    print(f"CHANGELOG:    {v_log or '(none)'}")
+
+    if v_toml != v_init:
+        print(f"\n  WARNING: pyproject ({v_toml}) != __init__ ({v_init})")
+    if v_log and v_toml != v_log:
+        print(f"\n  WARNING: pyproject ({v_toml}) != CHANGELOG ({v_log})")
+
+    print("\nUnreleased changes (internal voice — do NOT paste into CHANGELOG.md):")
+    if unreleased:
+        lines = unreleased.split("\n")
+        for line in lines[:12]:
+            print(f"  {line}")
+        if len(lines) > 12:
+            print(f"  ... ({len(lines) - 12} more lines)")
+    else:
+        print("  (none)")
+
+
+def cmd_check(new_version: str) -> None:
+    package = find_package()
+    current = get_current_version()
+    validate_version(new_version, current)
+
+    print(f"Package:    {package}")
+    print(f"Current:    {current}")
+    print(f"New:        {new_version}")
+    print("\nWould update (only these two files):")
+    print(f"  pyproject.toml:          {current} → {new_version}")
+    print(f"  {package}/__init__.py:   {current} → {new_version}")
+    print("\nThis script will NOT touch CHANGELOG.md, README.md, UNRELEASED.md, or git.")
+
+
+def cmd_bump(new_version: str) -> None:
+    package = find_package()
+    current = get_current_version()
+    validate_version(new_version, current)
+
+    print(f"Bumping {package} {current} → {new_version}\n")
+
+    bump_pyproject(new_version)
+    print(f"  ✓ pyproject.toml → {new_version}")
+
+    bump_init(package, new_version)
+    print(f"  ✓ {package}/__init__.py → {new_version}")
+
+    print(f"\n{'='*50}")
+    print(f"  Version bumped to {new_version}")
+    print(f"{'='*50}")
+    print("\nRemaining steps (all manual):")
+    print("  1. Verify CHANGELOG.md has a hand-written entry for this version")
+    print("     (do NOT paste UNRELEASED.md verbatim — translate to user-facing prose).")
+    print("  2. Verify README.md 'What's New' reflects the same user-facing summary.")
+    print("  3. git diff     # review")
+    print(f"  4. git add pyproject.toml {package}/__init__.py CHANGELOG.md README.md")
+    print(f"  5. git commit -m 'Release {new_version}'")
+    print(f"  6. git tag v{new_version}")
+    print(f"  7. git push origin <branch> && git push origin v{new_version}")
+    print("  8. python .release/release.py --reset-unreleased")
+    print("     git add .release/UNRELEASED.md && git commit -m 'Reset UNRELEASED.md'")
+    print("     git push")
+    print(f"  9. gh release create v{new_version} --title 'v{new_version}' --notes-file CHANGELOG.md")
+    print(f" 10. Verify: pip install {package}=={new_version}")
+
+
+def cmd_reset_unreleased() -> None:
+    reset_unreleased()
+    print(f"  ✓ {UNRELEASED_PATH.relative_to(REPO_ROOT)} reset to empty template")
+    print("\nRemember to commit the reset:")
+    print("  git add .release/UNRELEASED.md")
+    print("  git commit -m 'Reset UNRELEASED.md for next cycle'")
+    print("  git push")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+USAGE = """\
+Usage:
+  python .release/release.py --status              # show version state
+  python .release/release.py --check X.Y.Z         # dry-run: validate the bump
+  python .release/release.py --bump X.Y.Z          # bump pyproject.toml + __init__.py
+  python .release/release.py --reset-unreleased    # wipe UNRELEASED.md to template
+
+See the module docstring for the full manual release flow.
+"""
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(USAGE)
+        sys.exit(1)
+
+    arg = sys.argv[1]
+
+    if arg == "--status":
+        cmd_status()
+    elif arg == "--check":
+        if len(sys.argv) < 3:
+            print("Usage: python .release/release.py --check X.Y.Z")
+            sys.exit(1)
+        cmd_check(sys.argv[2])
+    elif arg == "--bump":
+        if len(sys.argv) < 3:
+            print("Usage: python .release/release.py --bump X.Y.Z")
+            sys.exit(1)
+        cmd_bump(sys.argv[2])
+    elif arg == "--reset-unreleased":
+        cmd_reset_unreleased()
+    else:
+        print(f"Unknown command: {arg}\n")
+        print(USAGE)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

{pystatistics-2.3.0 → pystatistics-3.0.1}/CHANGELOG.md

@@ -1,5 +1,182 @@
 # Changelog
 
+## 3.0.1
+
+Metadata and documentation polish. No API changes.
+
+- **Development Status classifier updated.** `pyproject.toml` now
+  declares `Development Status :: 5 - Production/Stable` (previously
+  `3 - Alpha`). This only affects the PyPI classifier — no runtime
+  behaviour changes.
+
+- **Stale optional-dependency extra removed.** The
+  `[nonparametric_mcar]` extra has been removed from `pyproject.toml`.
+  The subpackage it referenced was removed in 3.0.0, but the extra had
+  remained listed on PyPI. `pip install pystatistics[nonparametric_mcar]`
+  will now fail with an "extra not provided" message instead of
+  silently installing a dependency for a subpackage that does not exist.
+
+- **README restructured.** The README now leads with the library's
+  design philosophy and module table, with the changelog near the
+  bottom. A first-time reader on PyPI sees what PyStatistics is before
+  seeing what has changed release-to-release.
+
+## 3.0.0
+
+### BREAKING: Removed MoM MCAR test and the entire `nonparametric_mcar` subpackage
+
+`pystatistics.mvnmle.mom_mcar_test` and the full
+`pystatistics.nonparametric_mcar` subpackage (propensity / HSIC /
+MissMech + their shared `NonparametricMCARResult`) have been removed.
+These were added in 2.2.0 and 2.3.0 respectively, specifically in
+service of Lacuna's missingness-mechanism cache, NOT as general-
+purpose statistical methods. That was a scope-boundary mistake on
+pystatistics's part: we're a general-purpose statistics library, and
+these tests are project-specific feature-extraction helpers.
+
+**What remains in pystatistics:**
+  - `pystatistics.mvnmle.little_mcar_test` — the canonical Little (1988)
+    MLE-plug-in test. Textbook, general-purpose, stays.
+  - `MCARTestResult` dataclass — retained (downstream packages that
+    implement their own MCAR variants can and do reuse it).
+  - All of `mlest`, the EM / SQUAREM machinery, `analyze_patterns`,
+    `PatternInfo`, etc. — unchanged.
+
+**Where the removed tests live now:** the cache-scale variants have
+moved into Lacuna as `lacuna.analysis.mcar`:
+
+  - `lacuna.analysis.mcar.mom_mcar_test` (method-of-moments plug-in)
+  - `lacuna.analysis.mcar.propensity_mcar_test` (RF/GBM + analytical or
+    permutation null)
+  - `lacuna.analysis.mcar.hsic_mcar_test` (Gretton gamma or permutation null)
+  - `lacuna.analysis.mcar.missmech_mcar_test` (Jamshidian-Jalal-style)
+  - `lacuna.analysis.mcar.NonparametricMCARResult`
+
+All the 2.3.0/2.4.0 performance work that was in-flight in this file
+(analytical AUC p-value for propensity, HGB default, Gretton gamma
+null for HSIC, vectorised MissMech permutation, etc.) moved with the
+code. Downstream: Lacuna's cache build is unaffected — it now imports
+from `lacuna.analysis.mcar` instead of `pystatistics.nonparametric_mcar`.
+
+**Migration for external users (if any):**
+  - `from pystatistics.mvnmle import mom_mcar_test` →
+    `from lacuna.analysis.mcar import mom_mcar_test` (if using Lacuna).
+    Alternatively, the MoM algorithm is ~100 LOC of pairwise-deletion
+    moments + per-pattern chi-square and is straightforward to inline
+    if you don't want a Lacuna dependency.
+  - `from pystatistics.nonparametric_mcar import *` →
+    `from lacuna.analysis.mcar import *`.
+
+**Why a major bump (3.0.0):** public API surface shrunk; imports that
+worked in 2.x now fail. Even though our active user population is
+small (internal), the convention matters — breaking removals are
+semver-major.
+
+**Dropped files:**
+  - `pystatistics/nonparametric_mcar/` (subpackage, 5 files)
+  - `pystatistics/mvnmle/mcar_test.py` lost `mom_mcar_test`,
+    `_resolve_mom_backend`, `_pairwise_deletion_moments`, and the
+    `_MOM_GPU_WORTH_IT_THRESHOLD` constant. `little_mcar_test` and
+    `MCARTestResult` remain.
+  - `pyproject.toml` lost the `nonparametric_mcar` optional extra.
+  - `tests/mvnmle/test_mom_mcar.py` and `tests/nonparametric_mcar/`.
+
+(The dead batched MCAR chi-square machinery that this removal left
+stranded has also been cleaned up — see the "Dead-code cleanup"
+section below.)
+
+### Fixed flaky GAM GPU FP64 `total_edf` test
+
+`tests/gam/test_gam.py::TestGAMGPU::test_gpu_fp64_matches_cpu_fitted_and_gcv`
+had been flaking intermittently since 1.8.0. Measured CPU/GPU drift on
+the `sine_data` fixture:
+
+- `fitted_values` max abs diff: ~7e-8 (machine precision)
+- `deviance` relative diff: ~1e-7
+- `gcv` relative diff: ~3e-5
+- `total_edf` relative diff: **~1.4e-3** (narrowly failing the 1e-3 bar)
+
+Diagnosis: the primary fit statistics (fitted_values, deviance, GCV)
+sit at the GCV-minimising λ, i.e. at a local minimum of `GCV(λ)`, so
+they are insensitive to the tiny λ-drift the L-BFGS-B outer search
+lands on across CPU/GPU. `total_edf`, however, passes through a trace
+of `(X'WX + λ·S)⁻¹·X'WX`, which is LINEAR in λ near the optimum. With
+the penalised normal-equation matrix at cond ≈ 1e16-17 the EDF trace
+moves O(10⁻³) per O(10⁻⁶) λ shift — structurally more sensitive than
+the fit statistics that a 1e-4 tolerance gated.
+
+Fix: tolerance widened from `rel=1e-3` to `rel=5e-3` on `total_edf`
+only. The other three assertions (fitted_values, deviance, GCV) keep
+their 1e-4 margin. Test comment updated with the λ-sensitivity
+analysis so future maintainers don't re-tighten it without
+understanding why it's at 5e-3.
+
+### Fixed GAM GPU smooth-term chi-squared bug (null-space absorption)
+
+Surfaced while tightening the `total_edf` tolerance above: the chi-
+squared statistic reported in `smooth_terms` was diverging ~8×
+between CPU and GPU backends — CPU ≈ 19, GPU ≈ 156 on the
+`sine_data` fixture — despite fitted values agreeing to FP64
+precision. This was a latent correctness bug in the GPU backend
+going back to whenever the GAM GPU path was first written.
+
+Root cause: the penalised normal matrix `A = X'WX + Σ λⱼ Sⱼ` has
+condition number up to ~1e17 when λ is small — the penalty does not
+fully eliminate the design matrix's null space (the constant / linear
+directions in the spline basis's null space). On such `A`,
+`torch.linalg.solve` (LU on device) and `np.linalg.cholesky`
+(CPU reference path) converge to the same `X·β` (fitted values) but
+pick DIFFERENT null-space-representative `β` (coefficients).
+Concretely on `sine_data`: fitted values agreed to 7e-8 but
+coefficients were shifted by a constant ±1.73 between the parametric
+intercept and every smooth basis coefficient — exactly the null-space
+direction the penalty fails to constrain. Since `smooth_terms.chi_sq`
+is computed directly from `β` (via `β_j'·β_j / scale`), the null-
+space shift broke it despite the rest of the fit being numerically
+sound.
+
+Fix: the GPU backend now canonicalises the final `β` by re-solving
+`A·β = b` via numpy's Cholesky-with-LU-fallback — the same logic
+the CPU path uses in `_pirls_step`. This lives in a new
+`_canonicalise_beta` method; `fit_fixed` and `edf_per_term` both call
+it after their P-IRLS loops converge. In-loop P-IRLS still uses
+torch's fast LU on device (null-space ambiguity doesn't matter
+there — only the resulting `μ` drives convergence). The D2H
+round-trip for the final solve is ~100 µs on a p×p matrix with p
+typically ≤ 80; the dominant GPU work (the n×p GEMM in each P-IRLS
+step) stays on device.
+
+Test: `TestGAMGPU::test_gpu_fp64_matches_cpu_fitted_and_gcv` gained
+coefficient-level assertions (`rtol=1e-3, atol=1e-4`) and chi-squared
+agreement (`rel=1e-3`) so this regression is caught if it returns.
+Measured post-fix: coef max abs diff drops from 1.73 to 9e-5;
+chi_sq rel diff drops from ~8× to 1.6e-5.
+
+### Dead-code cleanup
+
+While removing ``mom_mcar_test``, noticed that the batched MCAR
+chi-square machinery (``chi_square_mcar_batched_np`` and
+``chi_square_mcar_batched_torch`` in ``backends/_em_batched_{np,torch}.py``,
+re-exported via the shim at ``backends/_em_batched.py``) was only ever
+called from ``mom_mcar_test``. Those functions are now gone; shim
+dropped their re-exports; backend file docstrings updated to record
+the removal. Net: `_em_batched_np.py` went from 416 → 300 lines and
+`_em_batched_torch.py` from 381 → 271 lines, and `backends/_em_batched.py`
+lost two of its eleven shim exports.
+
+### Process change
+
+Added **Rule 9 "Cross-Project Scope Boundary"** to
+`CLAUDE.md`. Future Claude Code sessions working on pystatistics must
+not modify sibling projects (Lacuna, pystatsbio, etc.) without
+explicit per-session user authorisation. Functionality needed by
+another project belongs in that project until demonstrably general.
+This removal is the retroactive correction of previous boundary
+crossings. The same rule was added to Lacuna's and pystatsbio's
+CLAUDE.md files (§8 and §9 respectively, numbered by where the rule
+fit in each file's existing structure).
+
+
 ## 2.3.0
 
 - **New subpackage `pystatistics.nonparametric_mcar`** for distribution-

{pystatistics-2.3.0 → pystatistics-3.0.1}/CLAUDE.md

@@ -218,6 +218,93 @@ file, that's a process failure.
 
 ---
 
+## 9. Cross-Project Scope Boundary — Stay in the Project You Were Invited Into
+
+A Claude Code session is invoked on one project. It does not have a licence to edit
+any other project visible on disk. Seeing sibling repos in `/mnt/projects/` does not
+constitute an invitation to modify them.
+
+**Rules:**
+- Never modify source, tests, configs, or documentation in a sibling project (any
+  repo outside the current one) on your own initiative.
+- When you believe a change belongs in a sibling project — "this belongs upstream",
+  "this helper is more general than the current project", "I should fix a bug in
+  their API" — stop and raise it with the user. Describe what you'd change, where,
+  and why. Wait for explicit authorisation before editing the sibling repo.
+- "Explicit authorisation" means the user said, in the current session, something
+  like "yes, also modify project X". It is NOT a precedent from a prior session. It
+  is NOT "the user probably wouldn't mind". It is NOT inferred from the fact that
+  the user depends on project X.
+
+**Corollary — Scope Creep Is a Design Decision, Not a Technical One:**
+Pushing project-A-specific functionality into general-purpose project B because it's
+technically convenient dilutes project B's identity, breaks the expectations of other
+downstream consumers, and forces project B to carry maintenance burden for a use case
+it was never meant to serve. "Project A needs X, and X involves statistics, therefore
+X belongs in pystatistics" is not a valid reasoning chain. X belongs in project A
+until (a) multiple sibling projects demonstrably need it AND (b) a decision has been
+made to promote it — either into an existing general-purpose library or into a new
+dedicated sibling.
+
+**What to do when you think a sibling needs a change:**
+1. Implement the helper inside your OWN project first. It lives there until proven
+   general.
+2. Surface the "belongs upstream" thought to the user explicitly. Propose the
+   migration as a separate task. Do not pre-emptively modify the sibling repo.
+3. If the user authorises the migration, treat it as its own first-class task with
+   its own review, tests, and release cadence — not as a side-effect of the
+   originating feature.
+
+---
+
+## 10. Audience Awareness for Public-Facing Files
+
+Before modifying any public-facing file (`README.md`, `pyproject.toml`,
+user-facing documentation, the PyPI description), explicitly identify the
+audience: **a stranger on the internet who has never seen this codebase.**
+That person has no knowledge of `CLAUDE.md`, internal project names,
+development rationale, rule numbers, or implementation history. They need
+to know what the library does, how to install it, and how to use it —
+nothing else.
+
+**The test:** *would a first-time user finding this on PyPI find this
+useful or confusing?* If confusing, omit it.
+
+**Rules (all specific instances of the principle above):**
+
+- **Changelog entries must not reference internal development artifacts.**
+  Entries in `README.md`, `CHANGELOG.md`, or any public-facing document must
+  never reference `CLAUDE.md`, internal rule numbers, internal project
+  names, development process, or test counts. Acceptable content:
+  user-facing behaviour changes, API additions/removals, bug fixes, and
+  performance numbers.
+
+  Example of what must **not** appear in a public changelog:
+  > "a new Cross-Project Scope Boundary rule (Rule 9) has been added to
+  > CLAUDE.md"
+
+- **Do not document `CLAUDE.md` changes in `README.md`.** When updating
+  `CLAUDE.md`, do not document those changes in `README.md` or any other
+  public-facing file. `CLAUDE.md` is internal developer guidance; `README.md`
+  reflects the public API, installation, and usage. `README.md` must never
+  reference `CLAUDE.md` by name or by implication.
+
+- **`README.md` is a user document, not a changelog mirror.** When updating
+  `README.md` from `CHANGELOG.md` or release notes, do not copy entries
+  verbatim or structurally. Translate them: extract only user-facing
+  behaviour changes, rewrite in present tense describing the library's
+  current state, and omit internal process details (references to
+  `CLAUDE.md`, rule numbers, internal project names, test counts,
+  development rationale). A user reading the README should understand what
+  the library does today — not the history of how it got there.
+
+**Corollary — The Internal Audience Already Has CLAUDE.md:**
+Rationale that belongs in `CLAUDE.md` does not need to be duplicated into
+public-facing files to "motivate" a change for users. Users do not need to
+be sold on the rule behind the change — only told what changed.
+
+---
+
 ## Meta-Rule
 
 If any of these rules feel inconvenient, that feeling is the point. These rules exist