update-phel - SKILL.md Agent Skill

name: update-phel description: Bump phel-lang/phel-lang dependency to the latest release in this website repo. Triggers on "update phel", "bump phel", "upgrade phel-lang", "new phel release". Handles composer constraint bump, lock refresh, and verifies the post-update hook regenerated config.toml. model: sonnet

Update phel-lang to latest

This repo pins phel-lang/phel-lang in composer.json and mirrors the active version in config.toml (used by the Zola site to render the version badge / install snippets). A post-update-cmd runs build/update-phel-version.php which rewrites config.toml from the installed package version - do not edit config.toml by hand.

Procedure

Find current + latest version.
```
composer show phel-lang/phel-lang | grep -E "^versions"
composer show phel-lang/phel-lang --all | grep -E "^versions" | head -1
```
First command shows installed (marked *). Second lists all tags - latest stable is first non-dev-* entry.
Bump constraint in composer.json. Edit the phel-lang/phel-lang line under require. Use caret on the minor (^0.40), matching existing style. Phel is pre-1.0 so minor bumps may break - read the changelog if anything fails later.
Update lock + run post-update hook.
```
composer update phel-lang/phel-lang --with-dependencies
```
This pulls the new package, refreshes composer.lock, then auto-runs php build/update-phel-version.php which rewrites config.toml phel_version = "vX.Y.Z". If config.toml did NOT change, the hook failed - investigate before committing.
Verify.
```
git diff config.toml          # should show phel_version bump
composer test                 # phpunit (45+ tests), must pass
composer test:snippets        # runs every ```phel doc block against the new runtime
```
composer test:snippets is the important one for a version bump: a new Phel release can rename core fns, move namespaces, or change printed output, which silently breaks documentation examples. The snippet baseline (build/doc-snippets-baseline.json) is empty, so ANY newly-broken snippet is reported as a regression and fails. See "When snippets break" below.
Scan prose for stale version strings. The snippet harness only runs ```phel blocks, so versions written in prose, JSON examples, and upgrade headings drift silently (they are never executed). After bumping to vX.Y.Z, grep for and update any that still name an older version:
```
grep -rnE '"phel-lang/phel-lang": *"\^0\.[0-9]+"|^## Upgrading|var-dumper' content/
```
Update at least:
- content/documentation/installation.md - the ## Upgrading to ... heading, the composer require phel-lang/phel-lang:^X.Y command, and a short breaking-changes list for the new minor (pull from the release notes).
- content/documentation/guides/coming-from-clojure.md - the example composer.json pin.
- content/documentation/tooling/php-tools.md - the symfony/var-dumper constraint should match this repo's own composer.json.
These prose fixes belong in the same commit or a follow-up docs: commit.
Commit. Use this exact subject (matches prior chore: bump phel-lang to 0.39.0 convention):
```
chore: bump phel-lang to X.Y.Z
```
For a clean bump, stage exactly composer.json, composer.lock, config.toml. If the new release added namespaces or broke snippets you will also have legitimate changes to build/tests/.../ApiJsonFileTest.php, content/**, and/or build/doc-snippets-baseline.json (see below) - those belong in the SAME commit or a follow-up docs:/test: commit, not discarded. Conventional commits, no Claude trailers (per global instructions).

Files touched (expected)

Clean bump (no API/snippet changes):

composer.json - constraint bump only (1 line)
composer.lock - phel-lang + transitive deps (often symfony/*)
config.toml - phel_version rewritten by post-update hook

A release that adds/renames core namespaces or changes runtime behaviour also legitimately touches:

build/tests/php/ApiGenerator/Integration/ApiJsonFileTest.php - the $expectedNamespaces list + its count (0.41 added edn, reflect, transit)
content/documentation/reference/api/*.md - regenerated by composer build
content/** and build/doc-snippets-baseline.json - if doc snippets broke

When tests fail after bump

Phel < 1.0: minor releases can rename core fns or change emit output. Check:

https://github.com/phel-lang/phel-lang/releases/tag/vX.Y.Z for breaking changes
Failing tests in build/tests/ - usually VersionUpdater or API page generation
Regenerate API artifacts: composer build (runs api-page.php, api-search.php, api-json.php, generate-releases.php)

If breakage is in Phel itself, do not patch the website to compensate - open an issue upstream and pin to the prior version.

When snippets break

composer test:snippets runs each ```phel doc block in content/ in an isolated phel run subprocess against the new runtime. The baseline (build/doc-snippets-baseline.json) is empty, so the suite is green only when every block either passes or carries an explicit skip. A new release commonly breaks blocks via renamed core fns, moved/renamed namespaces, or changed printed output (; => comments). Triage each reported file:line [error]:

Behaviour/name actually changed in Phel -> update the snippet to the new API and fix any ; => output comment to the real runtime output (Phel vectors print as @[...], strings keep quotes). This is the common case and the whole point of the check.
Genuinely non-runnable block (syntax template with placeholder ids, REPL transcript, intentional-error demo, web/server-context) -> add an  HTML comment on its own line directly above the phel fence. Do NOT use a ` phel skip ` fence info string (breaks syntax highlighting). Most templates are already skipped.

Iterate until composer test:snippets reports Failed: 0. Useful commands:

php build/run-doc-snippets.php content/path/to/file.md --verbose  # one file
php build/run-doc-snippets.php --update-baseline                  # only if you
# deliberately accept a new known-failure; prefer fixing/skipping over this.

Keep the baseline empty when possible - a non-empty baseline is debt, not a solution.