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.mdindex 8455a961f..fdc104b07 100644--- a/.claude/skills/bump-mthds/SKILL.md+++ b/.claude/skills/bump-mthds/SKILL.md@@ -1,13 +1,13 @@---name: bump-mthdsdescription: >- 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 newrelease broke, run the checks, and write the CHANGELOG entry — stopping beforethe commit. Use whenever the user says "bump mthds", "update mthds", "upgrademthds", "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 mthdsversion 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, itis a **breaking change to pipelex's own API**, and it has to reach the changelogas 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: pinmoved, lock regenerated, source adapted, checks green, changelog written, ledgersquared. **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 itmoves 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:```bashgrep -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 aworking 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 itmakes `uv lock` fail. If you notice the sibling is ahead, that is worthmentioning in your report (it is a preview of the next bump) but it does notchange 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 isnothing to do, and manufacturing lock churn is worse than reporting "alreadycurrent". 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 youare adopting, and this repo's changelog is read by people deciding whether anupgrade 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 shapethis 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 editorrather than a shell one-liner: `sed -i` takes a separate empty argument on macOSand an attached suffix on GNU/Linux, so no single invocation is portable, andthe `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 movesevery 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:```bashgrep -A1 '^name = "mthds"' uv.lock@@ -201,8 +212,10 @@ If `uv lock` reports the requirement is unsatisfiable, the version is almostcertainly not on PyPI yet. Re-run the query from step 2. If it genuinely isn'tpublished, 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 afterrelease cuts it into a version heading — do not add a `## [vX.Y.Z]` headingyourself, 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 therelease *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 youchanged, and the check that went green. `Closes <id>` goes in the PR body whenthe 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` commitsprotocol parity fixtures captured *from this engine*, so a change here thatalters 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 quoteit as part of the release. The helper script skips it for you.- **`MTHDS_STANDARD_VERSION` moves silently.** Nothing pins it; the suitediff --git a/.claude/skills/bump-mthds/scripts/upstream_notes.py b/.claude/skills/bump-mthds/scripts/upstream_notes.pyindex 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 livehazard rather than a theoretical one, because `mthds-python`'s working tree isroutinely 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 thenew one's is included.- A checkout that predates the target release cannot answer, and says so insteadof 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