rms-polymath 2.1.1__tar.gz → 2.3.0__tar.gz

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/dependency_management.md

@@ -32,7 +32,7 @@ description: Standards for declaring, installing, and maintaining Python project
 
 ## 5. Security and Maintenance
 
-- Run `pip audit` in CI to catch known vulnerabilities.
+- Run `pip-audit` in CI to catch known vulnerabilities.
 - Enable automated dependency update tooling (Dependabot, Renovate).
 - Review update PRs for breaking changes before merging.
 - Periodically remove unused dependencies to reduce attack surface.
@@ -47,6 +47,7 @@ Consolidate all tool configuration into `pyproject.toml` where supported:
 | coverage | `[tool.coverage.run]`, `[tool.coverage.report]` |
 | mypy | `[tool.mypy]`, `[[tool.mypy.overrides]]` |
 | ruff | `[tool.ruff]`, `[tool.ruff.lint]` — use explicit `select = [...]` for E, F, W, I, UP, B, SIM, C4, A, N, PT, RUF (see python) |
+| codespell | `[tool.codespell]`, plus `.codespell-dictionary.txt` for the word pairs its parser requires in a separate file |
 | setuptools_scm | `[tool.setuptools_scm]` |
 
 Do NOT create separate config files (`.coveragerc`, `.mypy.ini`, `.flake8`, `setup.cfg`) when the tool supports `pyproject.toml`.

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/doc_python.md

@@ -1,17 +1,18 @@
 ---
-description: Foundation standards for documenting a Python package with Sphinx, ReadTheDocs, and docstrings; shared by the README, user-guide, dev-guide, and how-to rules.
+description: Foundation standards for documenting a Python package with Sphinx, ReadTheDocs, and docstrings; shared by the README, user-guide, dev-guide, and how-to skills.
 ---
 
 # Python Documentation Foundation
 
 This rule defines the documentation system, prose conventions, docstring
 rules, and Sphinx build requirements that apply to **all** documentation in a
-Python package. The companion rules build on it:
+Python package. The companion skills (in `.claude/skills/`, loaded when a task
+calls for them) build on it:
 
-- `doc_readme` — the top-level `README`.
-- `doc_user_guide` — the end-user manual.
-- `doc_dev_guide` — the contributor / maintainer manual and API reference.
-- `doc_how_to` — task-focused how-to articles.
+- `doc-readme` — the top-level `README`.
+- `doc-user-guide` — the end-user manual.
+- `doc-dev-guide` — the contributor / maintainer manual and API reference.
+- `doc-how-to` — task-focused how-to articles.
 
 Read this rule first; the others assume its docstring, cross-reference, prose,
 and build requirements without repeating them.
@@ -30,11 +31,28 @@ and build requirements without repeating them.
 ## 2. Prose Conventions
 
 - One space between a sentence-ending period and the next sentence.
-- American spelling, not British (e.g. `color`, not `colour`).
+- American spelling, not British: `center` not `centre`, `color` not `colour`,
+  `normalize` not `normalise`. Enforced by `codespell`; see the allow-list in
+  `pyproject.toml` for the terms of art it is told to accept. A line that needs
+  a word the gate is right to flag -- a test whose subject is the misspelling,
+  an external API name -- carries an inline `codespell:ignore <word>` with the
+  reason beside it, rather than widening the allow-list for everyone.
 - Define each domain-specific term on first use.
 - Describe the **current** state of the software only. Never anchor prose to a
   moment in time or to migration history: avoid "new", "legacy", "old",
   "now", "recently", "as before", "backwards compatible", and similar framing.
+- Do not cite issue/ticket numbers in documentation prose or in docstrings. Both
+  describe how the software behaves, not the tracker items that shaped it; issue
+  numbers belong in commit messages, PR descriptions, and (only as a supporting
+  reference, never as the whole comment) inline `#` code comments.
+- This prohibition covers the documentation the package publishes: the README,
+  the user and developer guides, the how-to pages, and docstrings. It does not
+  cover `plans/` or `critiques/`, including their `archive/` subdirectories and
+  the README that indexes each one. Those are project records rather than
+  package documentation, and naming the issue that owns a piece of work is what
+  they are for: a plan states which issues a phase closes and which it leaves
+  open, and an archive index states which issues each retired document carried
+  forward. Cite freely there.
 - Do not use unicode smart quotes, em-dashes, or arrows inside `.py` files
   (they are acceptable in `.rst` and `.md`).
 
@@ -47,15 +65,15 @@ A single `conf.py` configures the whole tree. It MUST:
 - Derive the version from installed package metadata (e.g.
   `importlib.metadata.version`) rather than hard-coding a version string.
 - Enable, at minimum, these extensions:
-    - `sphinx.ext.autodoc` — pull API docs from docstrings.
-    - `sphinx.ext.napoleon` — parse Google-style docstrings.
-    - `sphinx.ext.viewcode` — link API docs to highlighted source.
-    - `sphinx.ext.intersphinx` — cross-link to the docs of Python and key
-      third-party dependencies; populate `intersphinx_mapping` accordingly.
-    - `myst_parser` — include Markdown files (the `README`).
-    - A diagram extension (e.g. `sphinxcontrib.mermaid`) when the guides use
-      diagrams; configure it for headless/client-side rendering so CI needs no
-      browser.
+  - `sphinx.ext.autodoc` — pull API docs from docstrings.
+  - `sphinx.ext.napoleon` — parse Google-style docstrings.
+  - `sphinx.ext.viewcode` — link API docs to highlighted source.
+  - `sphinx.ext.intersphinx` — cross-link to the docs of Python and key
+    third-party dependencies; populate `intersphinx_mapping` accordingly.
+  - `myst_parser` — include Markdown files (the `README`).
+  - A diagram extension (e.g. `sphinxcontrib.mermaid`) when the guides use
+    diagrams; configure it for headless/client-side rendering so CI needs no
+    browser.
 - Set `source_suffix` to include both `.rst` and `.md`.
 - Configure Napoleon for Google-style docstrings (`napoleon_google_docstring`,
   `napoleon_use_param`, `napoleon_use_rtype`).
@@ -85,16 +103,16 @@ A single `conf.py` configures the whole tree. It MUST:
 
 - EVERY mention of a code object in narrative prose MUST use the appropriate
   Sphinx cross-reference role so it links to the API reference:
-    - `:class:`~package.module.Class``
-    - `:meth:`~package.module.Class.method``
-    - `:func:`~package.module.func``
-    - `:mod:`package.module``
-    - `:attr:`~package.module.Class.attr``
-    - `:data:`~package.module.NAME``
+  - `:class:`~package.module.Class``
+  - `:meth:`~package.module.Class.method``
+  - `:func:`~package.module.func``
+  - `:mod:`package.module``
+  - `:attr:`~package.module.Class.attr``
+  - `:data:`~package.module.NAME``
   Use `:doc:` to link other documentation pages and `:ref:` for labeled
   sections.
 - Bare CamelCase or `module.symbol` text in prose is a violation, even when
-  wrapped in inline literals. Inline literals (`` `` ``) are for YAML/JSON
+  wrapped in inline literals. Inline literals (```` ``) are for YAML/JSON
   keys, file paths, CLI tokens, environment variables, and shell snippets —
   not for API symbols.
 - Cross-references are NOT required (and should be omitted) inside
@@ -128,4 +146,4 @@ sphinx-build -n -b html docs docs/_build   # nitpicky (catches broken xrefs)
 - NEVER leave stale or contradictory documentation. If a feature is removed,
   remove its documentation; if it is renamed, rename every reference.
 - A new public module requires a corresponding API-reference entry so it
-  appears in the rendered API surface (see `doc_dev_guide`).
+  appears in the rendered API surface (see the `doc-dev-guide` skill).

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/environment.md

@@ -12,7 +12,7 @@ description: Git, CI/CD (GitHub Actions), virtual environments, and tooling for
 ## 2. CI/CD
 
 - ALWAYS use **GitHub Actions** for continuous integration and publishing.
-- The local check runner (`scripts/run-all-checks.sh`, Section 3) is the **single source of truth** for which checks the repository runs. CI/CD MUST run the same set of checks the script enables -- no more, no less -- so that the AI, CI/CD, and the script stay consistent. A typical set is lint (`ruff`), type-check (`mypy`), test (`pytest`), Markdown lint (`PyMarkdown`), and documentation build (`sphinx-build`); the repository's actual enabled set is whatever the script defines. If a check is not enabled in the script, CI/CD does not run it either.
+- The local check runner (`scripts/run-all-checks.sh`, Section 3) is the **single source of truth** for which checks the repository runs. CI/CD MUST run the same set of checks the script enables -- no more, no less -- so that the AI, CI/CD, and the script stay consistent. A typical set is lint (`ruff`), type-check (`mypy`), test (`pytest`), spell check (`codespell`), Markdown lint (`PyMarkdown`), and documentation build (`sphinx-build`); the repository's actual enabled set is whatever the script defines. If a check is not enabled in the script, CI/CD does not run it either.
 - Every PR MUST pass that set of checks before merge.
 - When the enabled set changes, change it in the script first, then bring CI/CD into step with it in the same change.
 - Pin action versions to a major tag (e.g., `actions/checkout@v6`) to balance stability and security updates.

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/logging.md

@@ -90,4 +90,5 @@ local-or-remote handling is provided by `filecache`.
 | Named section + level | `with logger.open('HEADER', level='DEBUG'):` |
 | Per-unit handlers | `with logger.open(item_id, handler=handlers):` |
 | Exception in except block | `logger.exception('msg: %s', detail)` |
+| Stage handler that re-raises to the orchestrator | `logger.error('msg: %s', exc)` then `raise`; the orchestrator's `exception()` records the traceback once |
 | Standard-library logging | Only for type annotations in low-level plumbing |

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/python.md

@@ -14,26 +14,30 @@ Apply these rules to ALL new and modified Python code. This project is a Python
 - **Module-level constants (global variables)**: Use `ALL_CAPS_WITH_UNDERSCORES`.
 - **Private names**: Prepend a single underscore for names that are not part of the public API: private attributes (e.g. `_cache`), module-private global variables, and non-public helper functions (e.g. `_parse_header`). Public API names have no leading underscore.
 - **Built-in names**: Do NOT use variable or function names that shadow Python built-ins (e.g. `float`, `filter`, `id`, `list`, `type`). If you must use such a name, append a single underscore (e.g. `filter_`, `type_`).
+- **Falsy checks**: Be explicit about what you are testing. Do NOT rely on truthiness when the intent could be ambiguous. Prefer:
+  - `if x is None:` for None checks (not `if not x:` when 0 or [] could occur).
+  - `if len(seq) == 0:` when you explicitly mean "empty sequence" and other falsy values (0, None) are not possible.
+  - For dicts: `if key in d:` then use `d[key]`; avoid `d.get(key)` when you need to distinguish "missing" from "present with a falsy value" unless that is the intent.
 - **Explicit checks over exceptions**: Prefer explicit membership or presence checks over catching exceptions for control flow. Example: use `if "a" in b: x = b["a"]` (or a clear `get` with a sentinel) rather than `try: x = b["a"]` / `except KeyError: ...` for normal flow. Use exceptions for genuinely exceptional conditions.
 
 ## 2. General Coding
 
-- Always match the coding style of pre-existing Python files.
-- Always make the minimal changes necessary. Never modify code outside the scope of the current task.
-- Do not include backwards-compatibility code unless explicitly requested.
-- Always write simple, clear code; avoid unnecessary complexity.
-- Define magic constants as module-level constants, in a config module, or via environment variables.
-- Catch exceptions at the smallest granularity possible. Do not wrap large blocks in a single `try`/`except`.
+- ALWAYS match the coding style of pre-existing Python files.
+- NEVER include backwards-compatibility code unless explicitly requested.
+- ALWAYS write simple, clear code; avoid unnecessary complexity.
+- NEVER hardcode magic constants. Define them as module-level constants, in a config module, or via environment variables.
+- ALWAYS catch exceptions at the smallest granularity possible. Do NOT wrap large blocks in a single `try`/`except`.
 - **Libraries:** Let exceptions propagate unless you are adding context, converting to a library-specific exception, or the exception represents a recoverable internal state. When re-raising, use `raise ... from` to preserve the full traceback for debugging.
-- **Applications:** Do not allow uncaught exceptions to reach the top level; use a top-level handler (e.g. in the main loop or HTTP framework) so that failures are logged and the process stays predictable. In both cases, always provide full exception information for debugging (e.g. traceback, `raise ... from` when re-raising).
-- Include meaningful, structured logging (use the `logging` module) that can be disabled or redirected. Never use bare `print()` for diagnostic output in library code.
+- **Applications:** Do not allow uncaught exceptions to reach the top level; use a top-level handler (e.g. in the main loop or HTTP framework) so that failures are logged and the process stays predictable. In both cases, ALWAYS provide full exception information for debugging (e.g. traceback, `raise ... from` when re-raising).
+- ALWAYS include meaningful, structured logging that can be disabled or redirected. NEVER use bare `print()` for diagnostic output in library code.
 - Avoid mutable global variables. If unavoidable, document purpose and limit scope. Prefer module-level constants (ALL_CAPS) or dependency injection.
-- Always prefer comprehensions (list, dict, set, generator) over manual loops when the result is a new collection and the expression remains readable.
-- Apply DRY. Avoid duplicating code. Place reusable logic in a utility module. Search existing utilities before writing new functions. Parameterize utility functions to increase generality.
-- Place imports at the top of the file in three alphabetically-sorted groups separated by a blank line: (1) standard library, (2) third-party, (3) local project. When adding new code or tests, add new imports to the appropriate group at the top; do not place them adjacent to the new code. Inline imports are permitted only to avoid heavy optional dependencies (e.g., GUI libraries).
-- Limit new functions to at most 5 positional parameters. Additional parameters should be keyword-only (after `*`). Choose a logical grouping of 0-5 positional parameters before enforcing keyword-only parameters.
+- ALWAYS prefer comprehensions (list, dict, set, generator) over manual loops when the result is a new collection and the expression remains readable.
+- ALWAYS make the minimal changes necessary. NEVER modify code outside the scope of the current task.
+- ALWAYS apply DRY. NEVER duplicate code. Place reusable logic in a utility module. Search existing utilities before writing new functions. Parameterize utility functions to increase generality.
+- ALWAYS place imports at the top of the file in three alphabetically-sorted groups separated by a blank line: (1) standard library, (2) third-party, (3) local project. When adding new code or tests, add new imports to the appropriate group at the top; do not place them adjacent to the new code. Inline imports are permitted only to avoid heavy optional dependencies (e.g., GUI libraries).
+- Positional parameters are the values a caller naturally supplies together: one logical group, in an obvious order. Usually that is at most three, but four or five positional parameters are correct when they form a single logical unit (e.g. `self, pos_x, pos_y, pos_z`) -- NEVER split such a group with `*` just to satisfy a count. Optional and configuration parameters MUST be keyword-only (after `*`). If the leading logical group is larger than about five parameters, make all parameters (after `self`) keyword-only instead.
 - Use the Receive-an-Object, Return-an-Object (RORO) pattern when a function takes or returns more than a few related values: accept a dataclass or TypedDict and return one, rather than long positional tuples.
-- Never use `getattr` just as a defensive measure if it is guaranteed that the object has the attribute. Reference the attribute directly unless there is a specific reason to know the attribute may not be present. NEVER use getattr to reference the result of an `argparse` namespace when the argument name is a constant string.
+- NEVER use `getattr` just as a defensive measure if it is guaranteed that the object has the attribute. ALWAYS reference the attribute directly unless there is a specific reason to know the attribute may not be present. NEVER use getattr to reference the result of an `argparse` namespace when the argument name is a constant string.
 
 ## 3. Public API Design
 
@@ -45,7 +49,8 @@ Apply these rules to ALL new and modified Python code. This project is a Python
 ## 4. Comments
 
 - ALWAYS write self-documenting code: meaningful names, simple structure, limited nesting.
-- NEVER include comments that merely restate the code, reference user requests, or describe modification history.
+- NEVER write a comment whose ONLY content is a restatement of the code, a user request, or modification history. A comment must earn its place by describing behavior or rationale the code itself cannot show.
+- An issue/ticket number is welcome AS A REFERENCE once a comment already describes the behavior or rationale. Good: `# Cap the tier when the fit is rank-deficient: an unobservable axis is an assumption, not a measurement (#221).` — it explains the behavior and cites the issue for further context. Not acceptable: `# Fix for #221.` — that is only historical.
 - ALWAYS include comments that explain the **rationale** behind non-obvious or complex logic.
 - ALWAYS preserve existing comments that are still accurate and relevant. Remove or update stale comments.
 
@@ -54,25 +59,29 @@ Apply these rules to ALL new and modified Python code. This project is a Python
 ### Types
 
 - NEVER use type annotations in the src directory tree, with one exception. Types of input parameters and returns should be indicated in the docstrings. The exception is a property, which may carry an inline return annotation so that the rendered documentation shows the type beside the property name; a property annotated this way keeps a one-line docstring rather than a `Returns:` block.
-- Annotate all test function/method parameters and return values, including `-> None` for functions (and `__init__`) that return nothing.
+- ALWAYS annotate all test function/method parameters and return values, including `-> None` for functions (and `__init__`) that return nothing.
 - Use modern generic syntax (`list[str]`, `dict[str, int]`, `X | None`) for Python 3.11+.
 
 ### Mypy
 
-- NEVER run `mypy` on the src directory tree.
-- Run `mypy` on the tests after changes. Fix all errors before delivering.
+- NEVER run `mypy` on the src directory tree. It is deliberately unannotated; the `exclude` patterns and `ignore_errors` overrides in `pyproject.toml` exist only so that `mypy.stubtest` can check the two published stubs against it.
+- ALWAYS run `mypy` on the tests after changes. Fix all errors before delivering.
+- NEVER add other global type exclusions. "Global type exclusions" means:
+  - Module-level `# type: ignore` without a specific error code.
+  - `ignore_errors = True` in mypy config.
+  - Broad `exclude` patterns that skip entire packages.
 - In exceptional, unfixable cases use a minimal line-level ignore: `# type: ignore[error-code]  # <brief justification>`.
 
 ### Ruff / Linting
 
-- Include `mypy` and `ruff` in the project's dev dependencies (e.g. in `pyproject.toml`).
-- Run `ruff check` on the full codebase after changes
-- Follow PEP 8 for formatting and naming conventions.
+- ALWAYS include `mypy` and `ruff` in the project's dev dependencies (e.g. in `pyproject.toml`).
+- ALWAYS run `ruff check` on the full codebase after changes. Fix all errors. Do NOT run `ruff format`: the source uses deliberate column alignment that it would remove.
+- Follow PEP 8 for all formatting and naming conventions.
 - Use the project's explicit Ruff rule set in `pyproject.toml` (see **Ruff rule categories** below). Do not disable categories that enforce project conventions (e.g. **A** for no builtin shadowing, **N** for naming).
 
 ## 6. Docstrings
 
-- Include a docstring for every module, class, function, and method.
+- ALWAYS include a docstring for every module, class, function, and method.
 - Follow **PEP 257** using **Google style**. Use `Parameters:` (not `Args:`).
 - Include `Returns:`, `Raises:`, and any important behavioral notes.
 - NEVER mention backwards compatibility, a user request, change history, or an issue/ticket number in a docstring. Docstrings are usage documentation for the published API, not a place to explain the code's provenance; describe only observable behavior. (Issue references are allowed in inline `#` code comments per Section 4, and in commit messages and PR descriptions.)

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/python_testing.md

@@ -24,8 +24,10 @@ the same standard as the package they exercise.
 ## 2. Framework and Tooling
 
 - ALWAYS use `pytest`. Do not write `unittest.TestCase` classes for new tests.
-- ALWAYS use `pytest-cov` for coverage and `pytest-xdist` for parallelism; run
-  with `-n auto`. Declare all three in the dev dependency group.
+- ALWAYS use `pytest-cov` for coverage. `pytest-xdist` with `-n auto` should be
+  used if possible for parallelism but serial test runs may be required if the
+  code is not thread-safe. Declare appropriate options in the dev dependency
+  group.
 - ALWAYS put type annotations on test functions (parameters and `-> None`),
   exactly as on library code.
 - ALWAYS write tests that are independent and order-agnostic so they are safe to
@@ -69,11 +71,11 @@ Configure pytest under `[tool.pytest.ini_options]`; do not add separate
   name and scope them (`function`, `module`, `session`) to the broadest reuse
   that is still safe.
 - Use the built-in fixtures instead of hand-rolling isolation:
-    - `tmp_path` / `tmp_path_factory` for filesystem work — never write into the
-      repo or a fixed temp path.
-    - `monkeypatch` for environment variables, attributes, and `sys` state — it
-      auto-reverts after the test.
-    - `capsys` (or `capfd`) to capture and assert on stdout/stderr.
+  - `tmp_path` / `tmp_path_factory` for filesystem work — never write into the
+    repo or a fixed temp path.
+  - `monkeypatch` for environment variables, attributes, and `sys` state — it
+    auto-reverts after the test.
+  - `capsys` (or `capfd`) to capture and assert on stdout/stderr.
 - If a test must mutate global or class state that no fixture manages, restore
   the original value in a fixture teardown or a `try`/`finally` so it cannot
   leak into other tests (critical under parallel execution).

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/rules/security.md

@@ -14,7 +14,7 @@ description: Security best practices for Python library development — secrets,
 ## 2. Dependency Security
 
 - Specify minimum compatible versions for direct dependencies (e.g., `numpy>=2.2.0`) in `pyproject.toml`.
-- Run `pip audit` regularly and in CI to detect known vulnerabilities.
+- Run `pip-audit` regularly and in CI to detect known vulnerabilities.
 - Enable GitHub Dependabot for automated dependency update PRs.
 - Review changelogs and diffs before merging dependency updates.
 
@@ -34,7 +34,6 @@ description: Security best practices for Python library development — secrets,
 
 - NEVER log secrets, tokens, passwords, or full stack traces containing sensitive data.
 - Sanitize PII (personally identifiable information) before logging.
-- Use the `logging` module with appropriate levels so callers can control verbosity.
 
 ## 6. Code Review Security Checklist
 

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/skills/bug-report/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bug-report
-description: Standards for writing clear, reproducible bug reports, covering required components, severity levels, evidence, and environment details. Use when the user asks to write, file, or review a bug report or issue.
+description: Standards for writing clear, reproducible bug reports with severity, evidence, and environment details. Use when writing, filing, or reviewing a bug report or GitHub issue.
 ---
 
 # Bug Report Standards
@@ -56,8 +56,9 @@ Every bug report MUST include:
 ## Actual Behavior
 [What actually happens, including the full traceback.]
 
-## Traceback / Logs
-[Paste full traceback or relevant log output here]
+## Traceback / Logs / Screenshots / Other Evidence
+[Paste full traceback, relevant log output, screenshots, or other relevant evidence
+here when available]
 
 ## Additional Notes
 [Workarounds, frequency, related issues.]

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/skills/critique-documentation/SKILL.md

@@ -17,15 +17,15 @@ Analyze all of a project's documentation and produce a **report only** — do no
 
 ## Project rules
 
-If the repo contains a `.claude/rules/` directory, treat these documentation rule files as the authoritative standard and cite them by filename in findings:
+If the repo contains a `.claude/` directory, treat these documentation standards as authoritative and cite them by name in findings. `doc_python` is a rule in `.claude/rules/` (always loaded); the others are skills in `.claude/skills/` (read each `SKILL.md` directly):
 
-- `doc_python.md` — the **foundation**: documentation system, prose conventions, Sphinx `conf.py` essentials, docstrings, cross-reference completeness, and the build discipline (`-W` warnings-as-errors **and** `-n` nitpicky). Every other doc rule builds on it.
-- `doc_readme.md` — the top-level README: badges, the docs-inclusion marker, required sections, quickstart, and links.
-- `doc_user_guide.md` — the end-user manual: file layout, landing page + `toctree`, required content, configuration, and per-command-line-program references.
-- `doc_dev_guide.md` — the developer/contributor manual: layout, required chapters, class diagrams, per-module prose, extension recipes, and the API reference.
-- `doc_how_to.md` — task-focused how-to articles: structure, prerequisites, numbered steps, expected results, and troubleshooting.
+- `doc_python` (`.claude/rules/doc_python.md`) — the **foundation**: documentation system, prose conventions, Sphinx `conf.py` essentials, docstrings, cross-reference completeness, and the build discipline (`-W` warnings-as-errors **and** `-n` nitpicky). Every other doc rule builds on it.
+- `doc-readme` (`.claude/skills/doc-readme/SKILL.md`) — the top-level README: badges, the docs-inclusion marker, required sections, quickstart, and links.
+- `doc-user-guide` (`.claude/skills/doc-user-guide/SKILL.md`) — the end-user manual: file layout, landing page + `toctree`, required content, configuration, and per-command-line-program references.
+- `doc-dev-guide` (`.claude/skills/doc-dev-guide/SKILL.md`) — the developer/contributor manual: layout, required chapters, class diagrams, per-module prose, extension recipes, and the API reference.
+- `doc-how-to` (`.claude/skills/doc-how-to/SKILL.md`) — task-focused how-to articles: structure, prerequisites, numbered steps, expected results, and troubleshooting.
 
-Not every project ships every rule. **If a referenced rule file does not exist, ignore the corresponding part of the critique** instead of inventing a standard, and do not report the rule's absence as a finding. For example, if there is no `doc_how_to.md`, skip the how-to checks; if there is no `doc_dev_guide.md`, skip the developer-guide checks. Critique only against the doc rules that are actually present.
+Not every project ships every rule. **If a referenced rule file does not exist, ignore the corresponding part of the critique** instead of inventing a standard, and do not report the rule's absence as a finding. For example, if there is no `doc-how-to` skill, skip the how-to checks; if there is no `doc-dev-guide` skill, skip the developer-guide checks. Critique only against the doc rules that are actually present.
 
 ## Checklist for Analysis
 
@@ -38,7 +38,7 @@ Apply these criteria to the documentation set. Map each finding to the rule file
 - **Build cleanliness:** The docs build clean under BOTH `sphinx-build -W` (warnings-as-errors) and `sphinx-build -n` (nitpicky). Note any warnings, broken `toctree` entries, documents not in any `toctree`, or unresolved cross-references. Note `nitpick_ignore` entries that suppress symbols the project actually owns.
 - **Prose conventions:** American spelling; one space after sentence-ending periods; terms defined on first use; **no time-anchored or migration framing** ("new", "legacy", "now", "recently", "backwards compatible"). No unicode smart quotes/em-dashes/arrows inside `.py` files.
 
-### 2. Docstrings and API reference (`doc_python`, `doc_dev_guide`)
+### 2. Docstrings and API reference (`doc_python`, `doc-dev-guide`)
 
 - **Coverage:** Every module, class, method, and function has a docstring. Note missing or one-line-only docstrings on public objects.
 - **Format:** Google style with `Parameters:` (not `Args:`); `Returns:`/`Raises:` present where applicable; wrapped to the project width; describes observable behavior, not internals.
@@ -49,19 +49,19 @@ Apply these criteria to the documentation set. Map each finding to the rule file
 - **Roles:** Every mention of a code object in narrative prose uses the correct Sphinx role (`:class:`, `:meth:`, `:func:`, `:mod:`, `:attr:`, `:data:`); `:doc:`/`:ref:` link pages and labels. Note bare CamelCase or `module.symbol` text (even in inline literals) used for API symbols.
 - **Resolution:** All cross-references resolve under nitpicky mode. Note stale references to renamed/removed objects or moved pages (e.g. relative `:doc:` targets that broke when a page moved into a subdirectory).
 
-### 4. README (`doc_readme`)
+### 4. README (`doc-readme`)
 
 - **Format/inclusion:** Markdown; includable into Sphinx with a marker so host-only badges are excluded from the rendered docs; a single top-level title.
 - **Required sections (in order):** title, grouped status badges, introduction, features, installation (Python versions, prerequisites, install command), quick start, documentation link + local build, contributing link, license.
 - **Content:** Quickstart examples are runnable as written; every shipped command-line program or primary API is mentioned with a pointer to detailed docs; badge/version/entry-point claims match packaging metadata; all links resolve. The README is a summary and entry point, not a manual.
 
-### 5. User guide (`doc_user_guide`)
+### 5. User guide (`doc-user-guide`)
 
 - **Layout:** Lives in a dedicated `user_guide/` subdirectory; a landing page holds a short intro and a `toctree`; one chapter per feature or per command-line program; instrument/platform/format specifics in clearly named appendix pages; cross-directory `:doc:` targets are absolute, intra-guide ones relative.
 - **Required content:** introduction/purpose; an overview of the workflow/pipeline; installation and setup (versions, install commands, prerequisites, environment variables, expected input/output layout); the full configuration model with precedence and defaults; API usage where applicable; examples.
 - **Command-line program references:** For each program — name, one-line purpose, basic syntax, EVERY option documented (flag, argument, effect, default, env/config equivalents) grouped by purpose, positional/repeatable/value-set notes, at least one runnable example, and the schema of any structured file it consumes/emits. Note options that drift from the actual argument parser.
 
-### 6. Developer guide (`doc_dev_guide`)
+### 6. Developer guide (`doc-dev-guide`)
 
 - **Layout:** Lives in a dedicated subdirectory; a landing page lists chapters in reading order, ending with the API reference and contribution guide.
 - **Required chapters:** introduction (audience + package overview); annotated repository layout; environment setup (editable install, env vars, running entry points + smoke test, running the test suite with tiers/parallel/single-test, lint/type/format/docs commands and any wrapper, CI/CD, release, contribution workflow); architecture/class hierarchy; per-subsystem chapters; extending the system; coding conventions; API reference.
@@ -69,12 +69,12 @@ Apply these criteria to the documentation set. Map each finding to the rule file
 - **Per-module prose:** Each subsystem chapter gives an overview, per-class/per-file description with contracts (methods subclasses must implement and what they return), concrete implementations of each base, important invariants (thread-safety, shared mutable state, units/conventions), and a pointer to the API reference.
 - **Extending:** A step-by-step recipe per extension point with a minimal code skeleton and registration instructions.
 
-### 7. How-to articles (`doc_how_to`)
+### 7. How-to articles (`doc-how-to`)
 
 - **Structure:** Action-oriented title; 1-3 sentence intro; prerequisites; numbered steps (one action each, with the exact snippet/command and the observed result); an expected-results summary consistent with the per-step observations; troubleshooting of common failures; related-material links.
 - **Audience/consistency:** Written for a user unfamiliar with internals; where a how-to and the user guide cover the same workflow, they are consistent and link to each other rather than duplicating detail.
 
-### 8. Diagrams and figures (`doc_how_to`, `doc_dev_guide`)
+### 8. Diagrams and figures (`doc-how-to`, `doc-dev-guide`)
 
 - **Use and rendering:** Diagrams are used where a visual is clearer than prose (workflows, pipelines, architecture), placed inline near the relevant section, render in the docs build (validated in their authoring tool), and have descriptive filenames and alt text.
 
@@ -136,13 +136,13 @@ Produce a single markdown report with the following structure. Do **not** edit a
 [Self-contained prompt for an AI to apply the fixes. Include:
 - The report sections as context.
 - **Build gate:** The docs must build clean under BOTH `sphinx-build -W` and `sphinx-build -n` before the work is considered done.
-- Instruction to fix documentation according to the report and the present `.claude/rules/doc_*.md` rules, without changing production code behavior.
+- Instruction to fix documentation according to the report and the present documentation standards (`.claude/rules/doc_python.md` and the `.claude/skills/doc-*/SKILL.md` skills), without changing production code behavior.
 - Instruction to update every cross-reference and the README/guides in the same change when a symbol or page is renamed or moved.]
 ```
 
 ## Execution steps
 
-1. **Inventory rules:** List the `.claude/rules/doc_*.md` files that exist. Critique only against those; record which are absent so their checklist areas are skipped.
+1. **Inventory rules:** List which of `.claude/rules/doc_python.md` and `.claude/skills/doc-*/SKILL.md` exist. Critique only against those; record which are absent so their checklist areas are skipped.
 2. **Gather docs:** List the README and `docs/` tree (note the `toctree` structure and which pages are user guide vs. developer guide vs. how-to vs. API reference). Read `docs/conf.py`.
 3. **Build:** Run `sphinx-build -W -b html docs <out>` and `sphinx-build -n -b html docs <out>` (or the project's documented build) and capture warnings. If the docs cannot be built in this environment, say so and critique statically.
 4. **Read:** Sample the README, each guide landing page and representative chapters, a how-to, and a cross-section of docstrings. Grep for stale references, bare API symbols in prose, and time-anchored phrasing.

rms_polymath-2.1.1/.claude/rules/doc_dev_guide.md → rms_polymath-2.3.0/.claude/skills/doc-dev-guide/SKILL.md

@@ -1,8 +1,6 @@
 ---
-description: Format, layout, and completeness rules for the developer/contributor guide of a Python package, covering repository layout, class diagrams, per-module prose, and the API reference.
-paths:
-  - "docs/**/*.rst"
-  - "docs/**/*.md"
+name: doc-dev-guide
+description: Format, layout, and completeness rules for the developer/contributor guide of a Python package, covering repository layout, class diagrams, per-module prose, and the API reference. Use when writing, editing, or reviewing the developer guide or API reference under docs/.
 ---
 
 # Developer Guide
@@ -34,17 +32,17 @@ what the code already says.
   and a statement of which part is the importable public package versus
   supporting code.
 - **Environment setup** — how to get a working development checkout:
-    - Clone, virtual-environment creation, and an editable install with the dev
-      extras (`pip install -e ".[dev]"`).
-    - Every environment variable needed to run, test, or build, with defaults.
-    - How to run the package's entry points locally, including a smoke test.
-    - How to run the test suite: the default invocation, how to include slower
-      or integration tiers, parallel/CI-matching flags, running a single
-      file/test, and coverage. Note the test layout and any required markers.
-    - How to run linters, type checks, formatters, and the docs build, plus any
-      one-command wrapper that runs them all.
-    - The CI/CD pipeline (what runs on which trigger) and the release process.
-    - The contribution workflow, or a pointer to the contribution guide.
+  - Clone, virtual-environment creation, and an editable install with the dev
+    extras (`pip install -e ".[dev]"`).
+  - Every environment variable needed to run, test, or build, with defaults.
+  - How to run the package's entry points locally, including a smoke test.
+  - How to run the test suite: the default invocation, how to include slower
+    or integration tiers, parallel/CI-matching flags, running a single
+    file/test, and coverage. Note the test layout and any required markers.
+  - How to run linters, type checks, formatters, and the docs build, plus any
+    one-command wrapper that runs them all.
+  - The CI/CD pipeline (what runs on which trigger) and the release process.
+  - The contribution workflow, or a pointer to the contribution guide.
 - **Architecture / class hierarchy** — see Section 3.
 - **Per-subsystem chapters** — see Section 4.
 - **Extending the system** — see Section 5.

rms_polymath-2.1.1/.claude/rules/doc_how_to.md → rms_polymath-2.3.0/.claude/skills/doc-how-to/SKILL.md

@@ -1,14 +1,12 @@
 ---
-description: Format and completeness rules for task-focused how-to articles that walk a user through a single workflow with prerequisites, steps, and troubleshooting.
-paths:
-  - "docs/**/*.rst"
-  - "docs/**/*.md"
+name: doc-how-to
+description: Format and completeness rules for task-focused how-to articles that walk a user through a single workflow with prerequisites, steps, and troubleshooting. Use when writing, editing, or reviewing a how-to article.
 ---
 
 # How-To Articles
 
 A how-to article walks a reader through ONE concrete task from start to finish.
-It complements the reference material in `doc_user_guide`: the user guide
+It complements the reference material in the `doc-user-guide` skill: the user guide
 documents every option exhaustively, while a how-to picks one goal and shows the
 shortest correct path to it. Build on `doc_python` (prose conventions, build
 discipline). Where a how-to and the user guide describe the same workflow, keep
@@ -41,7 +39,7 @@ them consistent and link between them rather than duplicating detail.
 
 ## 3. Structure
 
-```markdown
+````markdown
 # How To [Action]
 
 [1-3 sentence introduction explaining purpose and value.]
@@ -72,7 +70,7 @@ them consistent and link between them rather than duplicating detail.
 ## Additional Information
 
 [Tips, performance notes, or links to related guides.]
-```
+````
 
 ## 4. Converting Technical Content
 

rms_polymath-2.1.1/.claude/rules/doc_readme.md → rms_polymath-2.3.0/.claude/skills/doc-readme/SKILL.md

@@ -1,7 +1,6 @@
 ---
-description: Format and completeness rules for the top-level README of a Python package, including badges, quickstart, and Sphinx inclusion.
-paths:
-  - "README.md"
+name: doc-readme
+description: Format and completeness rules for the top-level README of a Python package, including badges, quickstart, and Sphinx inclusion. Use when writing, editing, or reviewing the README.
 ---
 
 # README

rms_polymath-2.1.1/.claude/rules/doc_user_guide.md → rms_polymath-2.3.0/.claude/skills/doc-user-guide/SKILL.md

@@ -1,8 +1,6 @@
 ---
-description: Format, layout, and completeness rules for the end-user guide of a Python package, covering overview, configuration, and command-line program references.
-paths:
-  - "docs/**/*.rst"
-  - "docs/**/*.md"
+name: doc-user-guide
+description: Format, layout, and completeness rules for the end-user guide of a Python package, covering overview, configuration, and command-line program references. Use when writing, editing, or reviewing the user guide under docs/.
 ---
 
 # User Guide
@@ -92,4 +90,4 @@ For EACH command-line program the package installs:
   the program's actual argument parser and the packaging metadata. When the code
   changes, update the guide in the same change.
 - For step-by-step task walkthroughs that warrant their own article, follow
-  `doc_how_to` and link to it from the relevant chapter.
+  the `doc-how-to` skill and link to it from the relevant chapter.

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/skills/git-workflow/SKILL.md

@@ -10,7 +10,7 @@ description: Commit message format, branch naming, and the pull request workflow
 Write the subject as a plain capitalized sentence in the imperative mood, with no type
 prefix:
 
-```
+```text
 Add caching to profile lookup
 
 [Optional body — wrap at 72 characters. Explain *what* and *why*, not *how*.

{rms_polymath-2.1.1 → rms_polymath-2.3.0}/.claude/skills/pull-request/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: pull-request
-description: Standards for pull request structure, covering purpose, implementation details, testing evidence, and the review checklist. Use when the user asks to write a pull request description, open a PR, or review one.
+description: PR structure, purpose, implementation details, testing evidence, and review checklist. Use when writing a pull request title or description, or when reviewing a pull request.
 ---
 
 # Pull Request Standards
 
 ## Scope of review
 
-Treat the PR as a **single unit of change**. The diff to review is the set of all commits on the current branch back to its **immediate root** (the merge-base with the target branch). Consider the net result of those commits together; do **not** comment on differences that exist only between commits within the PR (e.g. "you fixed X in a later commit" or "commit 2 undid part of commit 1"). Review the final state of the branch against the base. Do not explicitly word wrap lines.
+Treat the PR as a **single unit of change**. The diff to review is the set of all commits on the current branch back to its **immediate root** (the merge-base with the target branch). Consider the net result of those commits together; do **not** comment on differences that exist only between commits within the PR (e.g. "you fixed X in a later commit" or "commit 2 undid part of commit 1"). Review the final state of the branch against the base. Do not explicitly word wrap lines; allow GitHub to flow them automatically.
 
 ## Principles
 
@@ -16,22 +16,20 @@ Treat the PR as a **single unit of change**. The diff to review is the set of al
 3. **Scope** — One logical change per PR. Split unrelated changes into separate PRs.
 4. **Testing evidence** — Document automated and manual testing performed.
 5. **Impact assessment** — Note potential effects on the public API, performance, or dependent packages (Potential Impacts section).
-6. **Linked issues** — Reference related GitHub issues using `Closes #NNN` syntax.
+6. **Linked issues** — Reference related GitHub issues using `Closes #NNN` syntax. Each issue must be listed separately like `Closes #NNN. Closes #MMM.`.
 
 ## Template
 
 The PR template is in `.github/pull_request_template.md` and is applied automatically when a new PR is opened. Fill out every section:
 
-- **Purpose** — Why the change is needed; link issue with `Closes #NNN`.
+- **Purpose** — Why the change is needed; link issue with `Closes #NNN. Closes #MMM.`.
 - **Changes / Implementation Details** — What changed and how it was implemented; technical approaches chosen and non-obvious design decisions.
-- **Type of Change** — Check all that apply (bug fix, feature, breaking, refactor, docs, tests, CI/build).
-- **Testing** — Check boxes for unit tests, integration tests, E2E tests run; describe new tests added and manual verification performed.
+- **Testing** — Describe tests changed and new tests added along with test results.
 - **Potential Impacts** — Public API, backward compatibility, performance, downstream; write "None" if straightforward.
-- **Checklist** — Style, mypy, docs, no debug code, no secrets/credentials, no warnings/errors, performance impact assessed, breaking changes flagged.
 - **Notes** — Optional; delete only if not needed (tricky areas, follow-up work).
 
 ## Guidance
 
 - **Library-specific** — Call out public API changes, deprecations, and migration notes in Potential Impacts.
 - **Required reviewers** — Tag maintainers for changes to core modules.
-- **Brevity vs. completeness** — Short enough that authors fill everything out; detailed enough for a reviewer with no other context.
+- **Brevity vs. completeness** — Short enough that authors fill everything out; detailed enough for a reviewer with no other context. If understanding the context for the change requires substantial knowledge, include a discussion of the motivation for the change and its details that is suitable for a reviewer with limited knowledge of the codebase and the concepts being discussed.