Stop claiming bfs is cost-optimal, and rewrite the contributing guide

The optimality sentence was wrong in a way that matters. `bfs` and
`iddfs` minimise plan *length*; that is only cost-optimality when every
action costs the same. On a four-action `:action-costs` domain with one
expensive shortcut, A* and Dijkstra return the three-step plan costing
3 and both of those return the one-step plan costing 10. `iddfs` is in
`OPTIMAL_PLANNERS` and the README did not even list it, so the two
disagreed in both directions. The source knew -- `uninformed.py` has
`optimal = True  # for unit-cost / plan-length` -- the README dropped
the qualifier. `awastar` needed its admissibility precondition back, and
`bnb`'s default 200 000-expansion ceiling is worth saying out loud,
since a run that hits it is no longer a proof of anything.

`docs/CONTRIBUTING.md` was an unadapted 2018 template. It told
contributors their work would be "licensed under its MIT License" -- the
project is Apache-2.0, as the same file says twenty lines earlier --
pointed "report bugs using Github's issues" at a stranger's unrelated
repository, offered an empty link for opening one, asked people to
branch from `master`, and spent a paragraph in the first person about
someone else's StackOverflow question about R. It now defers to the
org-wide guide and covers only what is specific here: the submodule, the
real floor, the commands CI runs, and the fact that this repo's
guarantee words are wired to an attribute the workbench publishes.

Also: the install line said Python 3.9 in the release whose changelog
announced the move to 3.10; `demos/` was described as six instances and
holds thirteen; `generate` was said to reproduce most of them, where it
reproduces two byte-for-byte; and the architecture tree omitted `learn/`
and `api.py` -- a headline feature and the module every library example
imports from.

Author: guilyx

.github/workflows/pages.yml

@@ -19,8 +19,9 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Not called `build`: .mergify.yml keys a merge rule on a check named
-  # `build`, and that must mean the packaging workflow, not this one.
+  # Not called `build`: that name belongs to the packaging workflow, and two
+  # checks with one name is a reliable way to gate a merge on the wrong one.
+  # (Mergify used to key a rule on it; Mergify is gone, the reasoning is not.)
   bundle:
     runs-on: ubuntu-latest
     steps:

README.md

@@ -9,6 +9,9 @@ actually *watch*. ✨
 **[▶ Open the workbench](https://openplan-labs.github.io/PythonPDDL/)** ·
 [Watch the 105-second tour](promo/jupyddl-promo.mp4)
 
+The repository is `PythonPDDL`; the package is `jupyddl`. That is what you
+install and what you import.
+
 </div>
 
 <div align="center">
@@ -72,7 +75,7 @@ is trivial to install, embed, teach with, and build on.
 
 ## Install 💾
 
-Requires Python ≥ 3.9, and nothing else:
+Requires Python ≥ 3.10, and nothing else:
 
 ```bash
 pip install jupyddl                 # the framework and the CLI
@@ -423,7 +426,7 @@ jupyddl benchmark demos --planners astar,gbfs,ehc,bfs --heuristic hff \
 
 ## Demo instances 🧪
 
-`demos/` holds six instances chosen to stress different parts of the framework —
+`demos/` holds thirteen instances chosen to stress different parts of the framework —
 and to make the difference between planners obvious:
 
 | Instance | What it exercises | Optimal cost |
@@ -442,8 +445,12 @@ and to make the difference between planners obvious:
 | `errands` | **preferences + constraints**: soft goals priced by a metric | 10 |
 | `timed-market` | **timed initial literals**: the plan waits for opening time | 4 |
 
-Most were produced by the generators, so `jupyddl generate` reproduces them
-exactly; `network` is hand-written because a recursive axiom is the point of it.
+Two of them are byte-for-byte generator output — `blocksworld12` is
+`generate blocksworld --size 12 --seed 3`, `workshop` is
+`generate workshop --size 3 --seed 1`. The rest were either hand-written
+(`sokoban`, `hanoi`, `elevator`, `errands`, `timed-market`, and `network`,
+whose recursive axiom is the point of it) or generated and then edited by hand,
+so `generate` will produce something equivalent but not identical.
 
 The `pddl-examples` git submodule supplies the smaller instances used by the
 parser and grounder tests.
@@ -459,10 +466,15 @@ parser and grounder tests.
 
 Heuristics: `blind`, `goalcount`, `hmax`, `hadd`, `hff`, `h1`, `h2`/`hm`, `lmcut`.
 
-`astar`, `idastar`, `bnb` and `dijkstra`/`bfs` are cost-optimal (the first three
-given an admissible heuristic — `blind`, `hmax`, `h1`/`h2`, `lmcut`). `awastar`
-lowers its weight until it reaches plain A*, so its last plan is optimal if the
-run completes. `hc`, `beam` and `iw` trade completeness for speed, and `iw` needs
+`astar`, `idastar` and `bnb` are cost-optimal given an **admissible** heuristic
+— `blind`, `hmax`, `h1`/`h2`, `lmcut`. `dijkstra` is cost-optimal
+unconditionally. `bfs` and `iddfs` minimise **plan length**, which is the same
+thing only when every action costs the same; on a domain with `:action-costs`
+they will happily return a shorter, more expensive plan. `bnb` also carries a
+default ceiling (200 000 expansions, depth 200), and a run that hits it is no
+longer a proof of optimality. `awastar` lowers its weight until it reaches
+plain A*, so its last plan is optimal if the run completes **and** the
+heuristic is admissible. `hc`, `beam` and `iw` trade completeness for speed, and `iw` needs
 no heuristic at all — it prunes by *novelty* instead.
 
 ## PDDL support 🧾
@@ -534,9 +546,13 @@ jupyddl/
   trace.py         search observers, events and serialisable traces
   live.py          zero-dependency live terminal dashboard
   generator.py     reproducible instance generators
+  learn/           heuristic learning: feature extraction, CEM, evaluation
+                   (the 'learn' extra; NumPy only makes it faster)
+  api.py           the library entry points -- solve, build_task, trace_search
   viz/             matplotlib theme, charts, animations (the 'viz' extra)
   benchmark.py     comparative benchmarking (CSV + plots)
-  cli.py           solve / benchmark / animate / demo / requirements / generate
+  cli.py           solve / benchmark / animate / demo / requirements /
+                   generate / learn
 web/               the Pyodide workbench
 tools/             web bundler and the promo-video renderer
 demos/             demo instances used by the docs, charts and video

docs/CONTRIBUTING.md

@@ -1,51 +1,64 @@
 # Contributing to PythonPDDL
-We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's:
 
-- Reporting a bug
-- Discussing the current state of the code
-- Submitting a fix
-- Proposing new features
-- Becoming a maintainer
+Thanks for showing up.
 
-## We Develop with Github
-We use github to host code, to track issues and feature requests, as well as accept pull requests.
+This repository is `openplan-labs/PythonPDDL`; the package it publishes is
+called **`jupyddl`**, which is what you import and what you `pip install`.
 
-## We Use [Github Flow](https://guides.github.com/introduction/flow/index.html), So All Code Changes Happen Through Pull Requests
-Pull requests are the best way to propose changes to the codebase (we use [Github Flow](https://guides.github.com/introduction/flow/index.html)). We actively welcome your pull requests:
+The [org-wide contributing guide](https://github.com/openplan-labs/.github/blob/main/CONTRIBUTING.md)
+covers the PR flow, commit style, and what a useful bug report contains. This
+page covers only what is specific to this repository.
 
-1. Fork the repo and create your branch from `master`.
-2. If you've added code that should be tested, add tests.
-3. If you've changed APIs, update the documentation.
-4. Ensure the test suite passes.
-5. Make sure your code lints.
-6. Issue that pull request!
+## Setting up
 
-## Any contributions you make will be under the Apache 2.0 Software License
-In short, when you submit code changes, your submissions are understood to be under the same [Apache 2.0](https://choosealicense.com/licenses/apache-2.0/) that covers the project. Feel free to contact the maintainers if that's a concern.
+The `pddl-examples` submodule supplies the instances the tests and benchmarks
+read, so clone with it:
 
-## Report bugs using Github's [issues](https://github.com/briandk/transcriptase-atom/issues)
-We use GitHub issues to track public bugs. Report a bug by [opening a new issue](); it's that easy!
+```bash
+git clone --recurse-submodules https://github.com/openplan-labs/PythonPDDL
+```
 
-## Write bug reports with detail, background, and sample code
-[This is an example](http://stackoverflow.com/q/12488905/180626) of a bug report I wrote, and I think it's not a bad model. Here's [another example from Craig Hockenberry](http://www.openradar.me/11905408), an app developer whom I greatly respect.
+Python 3.10 is the floor; CI runs 3.10 through 3.14.
 
-**Great Bug Reports** tend to have:
+```bash
+uv venv
+uv pip install -e ".[dev,viz,learn]"
+```
 
-- A quick summary and/or background
-- Steps to reproduce
-  - Be specific!
-  - Give sample code if you can. [My stackoverflow question](http://stackoverflow.com/q/12488905/180626) includes sample code that *anyone* with a base R setup can run to reproduce what I was seeing
-- What you expected would happen
-- What actually happens
-- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+## What CI will run
 
-People *love* thorough bug reports. I'm not even kidding.
+```bash
+flake8 jupyddl tests tools --count --statistics
+pytest
+black .            # CI reformats main automatically, but reviewers read diffs
+```
 
-## Use a Consistent Coding Style
-We use black to format automatically your PR to master. Please ensure PEP8 and PEP20 are respected.
+The `learn` extra is optional at runtime and its NumPy path is not exercised by
+every CI job. If you touch `jupyddl/learn/`, run the suite with it installed.
 
-## License
-By contributing, you agree that your contributions will be licensed under its MIT License.
+## Filing a bug
 
-## References
-This document was adapted from the open-source contribution guidelines for [Facebook's Draft](https://github.com/facebook/draft-js/blob/a9316a723f9e918afde44dea68b5f9f39b7d9b00/CONTRIBUTING.md)
+A parser or planner bug needs its input. Attach the **domain and problem
+files**, say which **planner and heuristic** you ran (`astar` alone is
+ambiguous; `astar` with `lmcut` is not), and give the exact command.
+
+If you are reporting that something is slow, conditions are part of the report:
+machine, instance, and how you measured. A number without them is not a result.
+
+## Changing a guarantee
+
+`optimal`, `complete`, `admissible` and `anytime` are load-bearing words here —
+`OPTIMAL_PLANNERS` in [`jupyddl/search/__init__.py`](../jupyddl/search/__init__.py)
+is derived from an `optimal` attribute on each planner, and the workbench
+publishes it. If a change moves a planner in or out of that set, or narrows the
+assumption a guarantee holds under, say so in the PR description.
+
+New planners and heuristics should cite the paper they implement — name and
+year — in the docstring. It tells a later reader which variant they are
+getting.
+
+## Licence
+
+This project is licensed under **Apache 2.0** (see [`LICENSE`](../LICENSE)). By
+contributing, you agree that your contributions are licensed under the same
+terms.