Tier 1: 0.1.0 release blockers — documentation drift + CI matrix

[cnicholas]

Findings from a three-agent deep audit (public API, internal code health, release readiness). Every item here is a blocker for tagging v0.1.0: each is the kind of drift a first-time PyPI user lands on in their first ten minutes.

Total effort: ~half a day. None require deep thought.

Documentation drift

• processbehavior/__init__.py:5,15 says "Design States (DS)" — every other surface uses SDS (Sampling Design State). PyPI landing page renders this docstring. Replace both occurrences with "SDS (Sampling Design State)".

• docs/getting-started/quickstart.ipynb (around lines 307, 2762) uses chart='Imr' — invalid; the real names are 'X' and 'mR'. The notebook prints Valid charts: ['Xbar', 'S', 'mR', 'Imr'] and then executes study.execute(chart='Imr', by=['lane']), which will raise ChartNotAvailableError for any user copy-pasting. Re-execute the notebook against current processbehavior and commit the regenerated cells.

• docs/getting-started/installation.md:11 falsely claims `openpyxl` is auto-installed. It's in the [excel] extra (`pyproject.toml:43`). Same drift in `docs/intro.md:127-131`. The README is correct. Move openpyxl to the optional section and add `numpy` to the auto-installed list.

• `processbehavior/study.py:1774-1779` `Raises` block says `ValueError` but the implementation raises `ValidationError` / `ChartNotAvailableError` / `FactorNotFoundError`. Same lie in `processbehavior/analysis_result.py:574-576, 606-609` (claims `KeyError`; actually `ChartNotAvailableError`). Sweep public `Raises` blocks across `study.py`, `analysis_result.py`, `capability.py`, `process_behavior.py`.

• `CLAUDE.md:31, 70, 140` still references retired `validation/TABVASTESTDATABASE.csv`. Corrected golden dataset is `validation/PBTESTDATABASE_T100.csv` (per the `[Unreleased]` changelog entry). Replace all three references.

CHANGELOG state

• `CHANGELOG.md:8-44` has the Xbar-center fix, `AnalysisResult.strata` fix, and `chart_table` dtype fix sitting under `[Unreleased]` after `[0.1.0] - 2026-05-03`. Tagging `v0.1.0` will publish a wheel whose own changelog claims those fixes are unreleased. Per CLAUDE.md: "move `[Unreleased]` into a dated section before tagging." Resolution options:
  • Bump to `0.1.1` (preferred — fixes landed after the 0.1.0 stamp), or
  • Rewrite `[0.1.0]` with today's date and absorb the `[Unreleased]` entries.
  • Update compare-link footers (`CHANGELOG.md:116-117` currently point at a v0.1.0 tag that doesn't exist yet).

CI matrix

• `.github/workflows/ci.yml:22-26, 105-106` — macOS dropped from regular CI to cut billing minutes. CLAUDE.md and Issue Release prep Phase 3: CI matrix, trusted publishing, and supply-chain hardening #77 both list macOS as a release-blocker matrix entry. The comment in the workflow already says "Reinstate before tagging the first PyPI release."
  • Defensible minimum: add `macos-latest` back for `python-version: ["3.13"]` only — one job, modest cost, honors the documented promise.
  • Full restoration (3 macOS jobs) can wait until after 0.1.0 if billing is a real concern.

Acceptance criteria

• `grep -rn "Design States (DS)" processbehavior/` returns no hits.
• `jupyter nbconvert --to notebook --execute docs/getting-started/quickstart.ipynb` runs clean.
• `grep -rn "openpyxl" docs/` shows it in optional-dependencies sections only.
• `grep -rn "Raises\s*$" processbehavior/study.py processbehavior/analysis_result.py` followed by inspection — all references match what the function actually raises.
• `git tag v0.1.1` (or `v0.1.0` after the rewrite) — CHANGELOG header reflects a dated release; `[Unreleased]` section is empty or removed.
• CI green on a macOS-included matrix before tagging.

Related

• Issue Release prep Phase 3: CI matrix, trusted publishing, and supply-chain hardening #77 tracks broader Phase 3 release-prep follow-ups.
• See also Tier 2 (#TBD) for 0.2.0 priorities and Tier 3 (#TBD) for longer-term polish.

---

Filed from a multi-agent audit synthesizing public-API, code-health, and release-readiness findings against the current library state.