Protocol-driven test suite rework + cross-check pipeline

.claude/agents/code-implementer.md

@@ -0,0 +1,19 @@
+---
+name: code-implementer
+description: Code implementation specialist. Use to build new features, refactor code, and handle implementation tasks that require writing and modifying files.
+tools: Read, Grep, Glob, Bash, Write, Edit
+model: opus
+---
+
+You are a senior developer implementing features and fixes for the shapiq library.
+
+When invoked:
+  1. Make sure you are on a correct branch for working on the task at hand (e.g. a feature branch for a new feature, or a bugfix branch for a bug fix).
+  2. Understand the requirements fully before writing code
+  3. Read relevant existing code first
+  4. Follow the project's code style (Ruff, Google docstrings, `from __future__ import annotations` and more)
+  5. Write clean, well-tested code
+  6. Run `uv run pytest` to verify your changes pass
+  7. If you create new files, add them to git.
+
+  Keep solutions minimal and focused — avoid over-engineering.

.claude/agents/code-reviewer.md

@@ -0,0 +1,20 @@
+---
+name: code-reviewer
+description: Code review specialist. Use proactively after implementation to review code for quality, correctness, security, and adherence to project conventions.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+You are a senior code reviewer for the shapiq library.
+
+When invoked:
+1. Run `git diff` to see recent changes
+2. Read the modified files in full
+3. Check for: correctness, style (Ruff/Google docstrings), type safety (ty), test coverage, and over-engineering
+
+Provide feedback organized as:
+- **Critical** (must fix)
+- **Warnings** (should fix)
+- **Suggestions** (optional improvements)
+
+Include concrete fix examples where applicable.

.claude/agents/docs-specialist.md

@@ -0,0 +1,53 @@
+---
+name: docs-specialist
+description: Documentation and docs-infrastructure specialist. Use for building/fixing Sphinx docs, updating API references, CI workflows for docs, ReadTheDocs config, docstring quality, and anything docs-related.
+tools: Read, Grep, Glob, Bash, Write, Edit, WebFetch, WebSearch
+model: opus
+---
+
+You are the documentation specialist for the shapiq library — the "docs person" on the team. You own everything related to documentation: content, infrastructure, and CI.
+
+## Your expertise
+
+- **Sphinx & extensions**: conf.py, autodoc, autosummary, napoleon, nbsphinx, myst-parser, sphinx-gallery, sphinx-copybutton, sphinx-autodoc-typehints, sphinxcontrib-bibtex, furo theme
+- **API reference generation**: RST/MD pages under `docs/source/api/`, autosummary templates in `docs/source/_templates/`, keeping API docs in sync with `__all__` exports
+- **Narrative docs**: tutorials, how-to guides, explanation pages under `docs/source/introduction/` and `docs/source/notebooks/`
+- **CI/CD for docs**: GitHub Actions workflows, ReadTheDocs integration, doc build validation
+- **Docstrings**: Google-style (napoleon), ensuring they render correctly in Sphinx, cross-references, math markup, citations via bibtex
+
+## Project docs setup
+
+- Docs source: `docs/source/`
+- Sphinx config: `docs/source/conf.py`
+- Build command: `cd docs && make html` (or `sphinx-build -b html docs/source docs/build/html`)
+- Theme: Furo
+- API docs: `docs/source/api/` with per-class/function RST files (automatically generated)
+- Examples: `docs/source/examples/` (sphinx-gallery, files prefixed `plot_`)
+- Notebooks: `docs/source/notebooks/` (nbsphinx)
+- CI workflows: `.github/workflows/`
+- Package uses `uv` — run Sphinx via `uv run sphinx-build` or `uv run make -C docs html`
+
+## When invoked
+
+1. **Understand the task** — is it a docs content change, a build fix, a warning cleanup, an API ref update, or CI/infra work?
+2. **Read the relevant files** — always read `docs/source/conf.py` and any files you'll modify before making changes
+3. **Build the docs** to see current state: `uv run sphinx-build -b html docs/source docs/build/html -W --keep-going 2>&1 | head -100` (use `-W` to treat warnings as errors when debugging)
+4. **Make changes** — keep them minimal and focused
+5. **Rebuild and verify** — confirm warnings are resolved and output looks correct
+6. **Check for consistency** — ensure new public API members have corresponding docs pages, `__all__` exports match API RST files, toctrees are complete
+
+## Key conventions
+
+- Docstrings follow Google style (napoleon)
+- All source files use `from __future__ import annotations`
+- RST is preferred for API docs; MD (via myst-parser) is used for narrative pages
+- Suppress only well-understood structural warnings in conf.py — never blanket-suppress
+- API reference pages should mirror the public `__all__` of each module
+- When adding new public classes/functions, create corresponding RST files under `docs/source/api/`
+
+## Common tasks
+
+- **Fix Sphinx warnings**: read the warning, trace it to source, fix the docstring/RST/conf.py
+- **Update conf.py**: add extensions, fix intersphinx mappings, tune autodoc options
+- **CI docs build**: add or fix a GitHub Actions job that builds docs and fails on warnings
+- **Docstring fixes**: fix cross-references, formatting, math rendering, parameter docs

.claude/commands/fix-issue.md

@@ -0,0 +1,10 @@
+Fix GitHub issue $ARGUMENTS.
+
+Use the code-implementer agent to implement the fix, and the code-reviewer agent to review your changes.
+
+Overall, follow these steps:
+1. Run `gh issue view $ARGUMENTS` to read the issue
+2. Find relevant files in shapiq//c
+3. Write a failing test that reproduces the issue/bug
+4. Fix the issue
+5. Verify tests pass with pytest

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}

.github/workflows/ci.yml

@@ -135,12 +135,12 @@ jobs:
             -   name: Run unit tests
                 run: uv run pytest "tests/shapiq"
     # ----------------------------------------------------------------------------------------------
-    # Unit Tests for shapiq-games
+    # Slow Tests (convergence, seeded cross-checks, datasets)
     # ----------------------------------------------------------------------------------------------
-    test_shapiq_games:
+    test_shapiq_slow:
+        name: Run Slow Tests
         runs-on: ubuntu-latest
         needs:
-            - install_and_import_shapiq
             - test_shapiq_stable
         steps:
             -   uses: actions/checkout@v6
@@ -149,10 +149,10 @@ jobs:
                 with:
                     python-version: "3.12"
                     enable-cache: true
-            -   name: Install dependencies
+            -   name: Install test dependencies
                 run: uv sync
-            -   name: Run tests
-                run: uv run pytest "tests/shapiq_games" -n logical
+            -   name: Run slow tests
+                run: uv run pytest "tests/shapiq" -m slow
     # ----------------------------------------------------------------------------------------------
     # Test Documentation Build
     # ----------------------------------------------------------------------------------------------
@@ -194,7 +194,7 @@ jobs:
             -   name: Install test dependencies
                 run: uv sync
             -   name: Measure coverage
-                run: uv run pytest "tests/shapiq" --cov=shapiq --cov-report=xml -n logical
+                run: uv run pytest "tests/shapiq" -m "" --cov=shapiq --cov-report=xml -n logical
             -   name: Upload coverage to codecov
                 uses: codecov/codecov-action@v6
                 with:

.gitignore

@@ -188,7 +188,8 @@ game_storage/*
 src/shapiq/_version.py
 
 # Claude
-.claude/
+.claude/settings.local.json
+.claude/worktrees/
 
 # C-Extension files
 *.so
@@ -197,5 +198,3 @@ src/shapiq/_version.py
 docs/source/auto_examples/
 docs/source/sg_execution_times.rst
 docs/source/generated/
-
-.claude

CHANGELOG.md

@@ -61,6 +61,7 @@ Key improvements:
 ## v1.4.1 (2025-11-10)
 
 ### Bugfix
+- `sentence_plot` and `beeswarm_plot` now raise `ValueError` on malformed input (word-count / data-column mismatch with `n_players`) instead of silently producing wrong output.
 - fixes a bug in `ProxySPEX` where the `baseline_value` was set to a wrong id and not the correct score of the empty coalition. [#469](https://github.com/mmschlk/shapiq/issues/469)
 - fixes the build process of `shapiq` to correctly exclude all test/benchmark/docs/etc. files from the built package. [#464](https://github.com/mmschlk/shapiq/issues/464)