Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

skill tweak

Louis Choqueldc67fc78c8a6
diff --git a/.claude/skills/bump-mthds/SKILL.md b/.claude/skills/bump-mthds/SKILL.md
index 8455a961f..fdc104b07 100644
--- a/.claude/skills/bump-mthds/SKILL.md
+++ b/.claude/skills/bump-mthds/SKILL.md
@@ -1,13 +1,13 @@
---
name: bump-mthds
description: >
- Move this repo's `mthds` dependency floor to the latest release on PyPI (or a
- version you name), re-lock, adapt the engine source to whatever the new
+ Move this repo's exact `mthds` dependency pin to the latest release on PyPI
+ (or a version you name), re-lock, adapt the engine source to whatever the new
release broke, run the checks, and write the CHANGELOG entry — stopping before
the commit. Use whenever the user says "bump mthds", "update mthds", "upgrade
mthds", "move to mthds 0.10.0", "get us on the latest mthds", "is our mthds
- floor stale", "what's the latest mthds", or asks to build against a newly
- published `mthds` release. Also use when a failure looks like an mthds
+ pin stale", "is our mthds floor stale", "what's the latest mthds", or asks to
+ build against a newly published `mthds` release. Also use when a failure looks like an mthds
version mismatch — a pyright `reportAttributeAccessIssue` on something under
`mthds.protocol`, an ImportError for a name that used to be there, a pydantic
`Extra inputs are not permitted` from a protocol model, or a `uv lock` saying
@@ -31,7 +31,7 @@ dependency: an upstream rename is not an internal detail this repo absorbs, it
is a **breaking change to pipelex's own API**, and it has to reach the changelog
as one.
-The job is to land the new floor in a state a human can read and commit: floor
+The job is to land the new pin in a state a human can read and commit: pin
moved, lock regenerated, source adapted, checks green, changelog written, ledger
squared. **Stop before committing** — the user stages and commits.
@@ -39,29 +39,38 @@ squared. **Stop before committing** — the user stages and commits.
| File | Why it moves |
|---|---|
-| `pyproject.toml` | The floor itself, one line in `[project].dependencies` — `mthds>=X.Y.Z` |
+| `pyproject.toml` | The pin itself, one line in `[project].dependencies` — `mthds==X.Y.Z` |
| `uv.lock` | Regenerated by `make li` |
| `pipelex/**` | Wherever the new release renamed, split, or tightened something this engine imports |
| `tests/**` | Same, plus any test asserting on a shape that moved |
-| `CHANGELOG.md` | An entry under `## [Unreleased]` — always at least the floor line |
+| `CHANGELOG.md` | An entry under `## [Unreleased]` — always at least the pin line |
| `.badges/tests.json`, `.test_durations` | Only if the adaptation added, removed or renamed tests |
Do **not** touch `[project].version`. That is this package's own version and it
moves only at release time, via the `release` skill.
-## The floor is a floor, and it always tracks latest
-
-The pin is `mthds>=X.Y.Z`, not `==`. pipelex is a published library, so the floor
-is a statement to *its* consumers about the minimum they must have.
-
-**The standing policy is to raise the floor to the latest release, every time**,
-even when the new release carries nothing this engine uses. Keeping the floor in
-lockstep with the lock means the version this repo tests against is the version
-it demands, with no gap for a consumer to fall into. The cost is real and worth
-naming when you report: everyone downstream — `pipelex-sdk-python`,
-`pipelex-server`, every user install — is forced onto that `mthds` too. Say so
-in the changelog when the bump is otherwise uneventful, because for a consumer
-"pipelex now requires mthds 0.10.0" *is* the change.
+## The pin is exact, and it always tracks latest
+
+The pin is `mthds==X.Y.Z`, not `>=`. That is deliberate and it is newer than it
+looks — the dependency was a `>=` floor until v0.54.0, which moved it to an
+exact pin and recorded the move as a breaking change. **Never relax it back to
+`>=` while bumping**, and never widen it to get a resolve unstuck.
+
+The reason is what this engine does with mthds: it re-exports mthds' wire models
+as part of pipelex's own public surface, so a consumer resolving a different
+mthds would be handed one version's classes through the `__all__` of a pipelex
+built against another — `isinstance` narrowing over a protocol union failing in
+a way no version specifier explains. An exact pin makes the version this repo
+tests against the version it demands, with no gap for a consumer to fall into.
+
+**The standing policy is to move the pin to the latest release, every time**,
+even when the new release carries nothing this engine uses. The cost is real and
+worth naming when you report: everyone downstream — `pipelex-sdk-python`,
+`pipelex-server`, every user install — is forced onto that exact `mthds`, and a
+consumer that also depends on `mthds` directly must now move in step with
+pipelex rather than resolving its own. Say so in the changelog when the bump is
+otherwise uneventful, because for a consumer "pipelex now requires mthds
+0.11.2" *is* the change.
## Three numbers, none of which is the others
@@ -82,17 +91,18 @@ in the upstream notes against this table before repeating it in ours.
### 1. Orient
-Read the floor **from `pyproject.toml`**, not from the virtualenv:
+Read the pin **from `pyproject.toml`**, not from the virtualenv:
```bash
grep -n '"mthds' pyproject.toml
.venv/bin/python -c "import importlib.metadata as m; print(m.version('mthds'))"
```
-They disagree more often than you would think, and each disagreement means
-something different. The venv ahead of the floor is normal — the floor is a
-minimum. The venv *behind* the floor means someone edited `pyproject.toml`
-without re-running `make li`.
+Under an exact pin these two should agree, in both directions — unlike a floor,
+where a venv running ahead was normal. Any disagreement means the venv is stale:
+someone edited `pyproject.toml` without re-running `make li`, or installed
+something over it. Re-sync with `make li` before you measure anything against
+the venv.
Check `git status` and note what was already dirty **before** you start.
Concurrent work in this worktree is normal, and at the end you need to separate
@@ -126,16 +136,16 @@ curl -s https://pypi.org/pypi/mthds/json \
```
`info.version` is the latest non-prerelease, which is what "latest" means for a
-floor other people inherit.
+pin other people inherit exactly.
**Ask PyPI, never the sibling checkout.** `mthds-python/pyproject.toml` is a
working tree and is frequently *ahead* of what has been published — a version
-sitting there under `## [Unreleased]` is not installable, and a floor naming it
+sitting there under `## [Unreleased]` is not installable, and a pin naming it
makes `uv lock` fail. If you notice the sibling is ahead, that is worth
mentioning in your report (it is a preview of the next bump) but it does not
change the target.
-If the resolved version equals the current floor, say so and stop: there is
+If the resolved version equals the current pin, say so and stop: there is
nothing to do, and manufacturing lock churn is worse than reporting "already
current". If the venv disagrees, mention that — `make li` is the real fix there.
@@ -151,7 +161,7 @@ cascade into a set of expected edits:
```
The helper reads `../mthds-python/CHANGELOG.md` and prints the released sections
-strictly after the old floor up to and including the new one. It skips
+strictly after the old pin up to and including the new one. It skips
`## [Unreleased]` — that section describes work that is *not* in the version you
are adopting, and this repo's changelog is read by people deciding whether an
upgrade will break them. If the checkout predates the target release the script
@@ -166,10 +176,11 @@ imports, parse-time tightening (mthds models are `extra="forbid"`, so a shape
this engine constructs can start failing at construction), and any move of
`MTHDS_STANDARD_VERSION`.
-### 4. Move the floor
+### 4. Move the pin
-One line in `pyproject.toml`. Make it a substring edit — replace `>=0.9.0` with
-`>=0.10.0` on that line and leave every other character alone. Use your editor
+One line in `pyproject.toml`. Make it a substring edit — replace `==0.11.1` with
+`==0.11.2` on that line, **keeping the `==`**, and leave every other character
+alone. Use your editor
rather than a shell one-liner: `sed -i` takes a separate empty argument on macOS
and an attached suffix on GNU/Linux, so no single invocation is portable, and
the `release` skill edits this same file the same way.
@@ -188,10 +199,10 @@ downstream of here depends on.
**Do not reach for `make update`.** That is `uv lock --upgrade` and it moves
every dependency in the tree at once, which turns a reviewable one-package bump
-into a diff nobody can reason about. Raising the floor is already enough to make
-plain `uv lock` re-resolve mthds upward.
+into a diff nobody can reason about. Moving the pin is already enough to make
+plain `uv lock` re-resolve mthds.
-Check the lock actually moved — a floor edit that didn't take is silent:
+Check the lock actually moved — a pin edit that didn't take is silent:
```bash
grep -A1 '^name = "mthds"' uv.lock
@@ -201,8 +212,10 @@ If `uv lock` reports the requirement is unsatisfiable, the version is almost
certainly not on PyPI yet. Re-run the query from step 2. If it genuinely isn't
published, stop and tell the user rather than inventing a git or path source:
adding one is a deliberate decision with a real cost (in uv, a *source* outranks
-a version specifier, so the floor you wrote becomes decorative), not a
-workaround to apply quietly.
+a version specifier, so the pin you wrote becomes decorative), not a workaround
+to apply quietly. An exact pin can also be reported unsatisfiable because
+another member of the resolve wants a different mthds — widening this pin is not
+the fix, moving the other requirement is.
### 6. Check whether `MTHDS_STANDARD_VERSION` moved
@@ -292,12 +305,13 @@ Add to `CHANGELOG.md` under `## [Unreleased]`, creating that heading right after
release cuts it into a version heading — do not add a `## [vX.Y.Z]` heading
yourself, and do not bump `[project].version`.
-Every bump gets at least the floor line. Follow the house form, which names the
+Every bump gets at least the pin line. Follow the house form, which names the
release *by what it carries*:
```markdown
-- **Minimum `mthds` version**: The floor moves to `mthds>=0.10.0`, <the release
- that carries / the release fixing …>.
+- **`mthds` version**: The pin moves to `mthds==0.11.2`, <the release that
+ carries / the release fixing …>. Everyone downstream inherits that exact
+ version.
```
Anything that reached pipelex's own surface gets its own entry under
@@ -315,11 +329,15 @@ ones harder to spot.
- **Close what you actually landed**, with evidence — the file and line you
changed, and the check that went green. `Closes <id>` goes in the PR body when
the user opens one.
-- **File the cascade.** A breaking bump here does not stay here.
- `pipelex-sdk-python` declares its own `mthds` floor, and `pipelex-server` pins
- `pipelex` exactly at several sites. Neither is yours to edit from this repo:
- file it (`ledger new --owner <repo> …`) with the symbol that moved and the
- version that moved it. The `ledger` skill has the full gesture.
+- **File the cascade, and note that the exact pin makes it sharper.**
+ `pipelex-sdk-python` pins `mthds` exactly too, and `pipelex-server` pins
+ `pipelex` exactly at several sites — so any bump here, breaking or not, puts
+ a consumer that installs both this package and `pipelex-sdk-python` into an
+ unsatisfiable resolve until that repo moves to the same version. Check where
+ it stands (`grep mthds ../pipelex-sdk-python/pyproject.toml`) and say so in
+ your report. Neither repo is yours to edit from here: file it
+ (`ledger new --owner <repo> …`) with the version that moved and, when there
+ was one, the symbol. The `ledger` skill has the full gesture.
- **File the reverse direction if you moved the wire.** `mthds-python` commits
protocol parity fixtures captured *from this engine*, so a change here that
alters emitted output means those fixtures need recapturing — an item owned by
@@ -330,7 +348,7 @@ ones harder to spot.
Show the user:
-- The floor move, old → new, and whether `uv.lock` actually followed.
+- The pin move, old → new, and whether `uv.lock` actually followed.
- Whether `MTHDS_STANDARD_VERSION` moved, and what that changes for users.
- Every file you changed, separated from what was already dirty when you started.
- The check results, honestly — if `agent-test` failed, say so with the output
@@ -348,13 +366,16 @@ and PRs target `dev`.
## Traps worth remembering
-- **The floor is not the lock.** Because `>=` already admits newer releases, a
- fresh resolve can pull a new mthds into someone's environment with nobody
- bumping anything. That is exactly why this bump is done deliberately, and why
- step 5 verifies the lock actually moved.
+- **Nothing in this repo enforces the `==`.** No check fails if the pin is
+ relaxed to `>=`; `pyproject.toml` is the only place the policy is written, and
+ the changelog is where it was announced. A widened pin ships silently.
+- **The pin is not the lock.** Editing `pyproject.toml` without re-locking
+ leaves `uv.lock` on the old version, which is what the venv and the suite
+ actually use — a green run against the version you meant to leave behind.
+ That is why step 5 verifies the lock actually moved.
- **The sibling checkout is routinely ahead of PyPI.** Read `mthds-python`'s
- changelog for *understanding*, PyPI for *the target version*. A floor naming
- an unpublished version fails `uv lock`.
+ changelog for *understanding*, PyPI for *the target version*. A pin naming an
+ unpublished version fails `uv lock`.
- **`## [Unreleased]` upstream is not in the version you adopted.** Never quote
it as part of the release. The helper script skips it for you.
- **`MTHDS_STANDARD_VERSION` moves silently.** Nothing pins it; the suite
diff --git a/.claude/skills/bump-mthds/scripts/upstream_notes.py b/.claude/skills/bump-mthds/scripts/upstream_notes.py
index f7895e515..ab6c1e93a 100755
--- a/.claude/skills/bump-mthds/scripts/upstream_notes.py
+++ b/.claude/skills/bump-mthds/scripts/upstream_notes.py
@@ -12,7 +12,7 @@ Three boundaries this exists to get right:
error about what the upgrade contains -- and in this pairing it is a live
hazard rather than a theoretical one, because `mthds-python`'s working tree is
routinely ahead of PyPI.
-- The old floor's own section is excluded (it was already in effect) while the
+- The old pin's own section is excluded (it was already in effect) while the
new one's is included.
- A checkout that predates the target release cannot answer, and says so instead
of printing a plausible-looking short range.
@@ -81,7 +81,7 @@ def split_sections(text: str) -> list[tuple[str, str]]:
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
- parser.add_argument("old_version", help="the floor currently declared, excluded from the output")
+ parser.add_argument("old_version", help="the version currently pinned, excluded from the output")
parser.add_argument("new_version", help="the version being adopted, included in the output")
parser.add_argument(
"--changelog",
@@ -122,7 +122,7 @@ def main() -> int:
print("\n\n".join(body for _, body in wanted))
if low not in known:
print(
- f"\nNote: no section for the old floor {args.old_version} in this checkout, so the range may start earlier than the true gap.",
+ f"\nNote: no section for the old pin {args.old_version} in this checkout, so the range may start earlier than the true gap.",
file=sys.stderr,
)
return 0