Skip to content

Releases

v0.8.4

Choose a tag to compare

@github-actions github-actions released this 15 Nov 22:48

v0.8.4 (2026-11-15)

This release is published under the MIT License.

Bug Fixes

  • types: Check every function body with mypy (4656f9f)

forge's Python template turns on check_untyped_defs, so mypy reads the body of an unannotated function as well. This carries the regenerated setting with the fixes its findings needed.

The tests assert attach returned a model and walk found a TyperGroup before reading either.

Agent-Name: claude-code

Agent-Session: 656acd51-ad66-4ec5-97ca-0e4d3b31c261

Worklog: 3473.1

Chores

  • Apply what repos-toolchain-rollout changed (18434f2)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job, and fleet committed it through the repo's hooks.

Agent-Run: 01a1b901-046f-7c92-9a16-414fad8e39fe

  • Apply what repos-toolchain-rollout changed (c5a8a08)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job, and fleet committed it through the repo's hooks.

Agent-Run: 01a1b5a1-9f55-7c35-8b73-9e67bad041fd

  • Apply what repos-toolchain-rollout changed (f3556ee)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job, and fleet committed it through the repo's hooks.

Agent-Run: 01a19f73-6093-7307-a7fb-a3e7f8833f46

  • Apply what repos-toolchain-rollout changed (737360f)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job and exited 3, and fleet committed it through the repo's hooks.

Agent-Run: 01a19cc6-9cbc-7ff7-ac4a-c2b6fcb8a555

  • Ignore the HTML coverage report task test:coverage writes (64679bb)

task test:coverage passes --cov-report=html, which writes htmlcov/. .gitignore covered .coverage and coverage.xml but not htmlcov/, so every coverage run left an untracked directory until task clean removed it. Ignoring it lets the coverage task leave the tree clean.

Agent-Name: inbox.problem.fix

Agent-Session: 01a1c30f-5d3d-7298-9b76-b0ae25d4d7cf

Agent-Run: 01a1c30f-1bf9-71aa-85f4-c0a0fd84292e

  • ci: Regenerate the hooks and CI at toolchain stamp 47 (06cd22d)

ruff-pre-commit moves to v0.17.1, and ruff's dev pin with it.

  • ci: Regenerate the hooks and CI at toolchain stamp 48 (101b3b4)

ruff-format selects Python files only, so it leaves the Python fences in Markdown alone.

  • ci: Regenerate the hooks and CI at toolchain stamp 49 (456f879)

Stamp 49 moves the pinned Go toolchain to 1.26.10.

Agent-Name: claude-code

Agent-Session: 7a0adaf6-eece-43c4-be4d-09eafeef1b43

  • ci: Regenerate the hooks and CI at toolchain stamp 53 (859737c)

shellcheck and hadolint install their release binaries through pip rather than running a Docker image, so a commit needs no Docker daemon.

Agent-Name: claude-code

Agent-Session: e236b085-15b5-4c8e-a91f-6501028cb83e

  • ci: Regenerate the hooks and CI at toolchain stamp 54 (317a6f2)

Agent-Name: claude-code

Agent-Session: 3334622e-8d87-4630-89c1-dc3bfeb197ed

  • ci: Regenerate the hooks and CI at toolchain stamp 55 (86cf2b6)

Agent-Name: claude-code

Agent-Session: d5c4cda8-3f7b-4483-a8b5-ba4de5a7cc8b

  • ci: Regenerate the hooks and CI at toolchain stamp 56 (02a039a)

The bats setup installs the pinned yq and rg the suites call.

Agent-Name: claude-code

Agent-Session: d5c4cda8-3f7b-4483-a8b5-ba4de5a7cc8b

  • ci: Regenerate the hooks and CI at toolchain stamp 58 (5525ee4)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job and exited 3, and fleet committed it through the repo's hooks.

Agent-Run: 01a1bf87-6f6c-7d56-8528-7660240e6a78

  • ci: Regenerate the hooks and CI at toolchain stamp 59 (c13df9c)

env FORGE_REPOS_REGISTRY=$FLEET_LIBRARY_DIR/repos.json FORGE_VERSIONS_FILE=$FLEET_LIBRARY_DIR/pinned-versions.json forge repos apply --yes wrote this in fleet's repos-toolchain-rollout job, and fleet committed it through the repo's hooks.

Agent-Run: 01a1dad9-516a-71bf-8580-68a8605cfbf9

Continuous Integration

  • Queue release runs, and lint workflows with jactionlint (6acb42b)

A concurrency group holds one pending run, so a third push cancelled the release run that was waiting. queue: max keeps up to 100 waiting, in order.

rhysd/actionlint's last release refuses the queue key, so the workflow lint hook runs jdx/jactionlint, a fork that accepts it and reads the same .github/actionlint.yaml.

Agent-Name: claude-code

Agent-Session: e8e6a3eb-37b1-47cd-9513-56f04276dc6d

  • Run the jactionlint hook in CI (f12f4ae)

The workflow's hook list names the id the pre-commit config now carries.

Agent-Name: claude-code

Agent-Session: e8e6a3eb-37b1-47cd-9513-56f04276dc6d

  • Run the uv and terraform the declaration pins in every workflow (535ec23)

A setup-uv or setup-terraform step naming no version installs the newest release on the day, while validate.yml runs the pinned one. forge's ci die now adds the missing input at the declared release, and writes the rest of what it generates at that release.

Agent-Name: claude-code

Agent-Session: e038c51a-a88b-4156-a8b6-13b8e667d702

Documentation

  • Keep each mechanism in the docstring of the code that runs it (8e65e32)

CLAUDE.md restated five mechanisms that module and function docstrings already explain: why the walk cannot use isinstance on click's classes (walk.py), why teaching writes to typer's CommandInfo and TyperInfo (teach.py), how the ledger keys a node (ledger.py), why state and cache are namespaced by library (paths.py), and each case where expansion declines (resolve.py). Every change to one of them had to edit two copies, and the copy in CLAUDE.md is not where the edit happens, so it goes stale while still reading as correct.

Each passage now keeps its one-line constraint and names the file and symbol whose docstring holds the reasoning. The docstrings are unchanged.

Agent-Name: inbox.problem.fix

Agent-Session: 01a1ddf5-f1cf-7042-b48f-8039b712e5f9

Agent-Run: 01a1ddf5-df95-7303-94cf-08857dd059d5

  • Make each docstring and README passage say its point once (85b17e8)

Eleven passages restated the sentence beside them, ranked a failure against nothing, named a set without listing it, broke a line short of the wrap column, or named a sibling tool and its private filename as the example of another library writing into a tool's state directory. A reader paid for each one with a reread or a lookup.

This rewraps the docstrings in assign.py and resolve.py and drops the repeated sentence from model.py, teach.py, tests/apps.py and tests/test_assign.py. It names the two bounds match_child checks. The paths.py example becomes a self-updater in general terms, and the README says what a recycled sequence does instead of calling it the worst failure.

  • Name write_atomically and paths.py as the only way to write a file (3b278ab)

Every file the library writes goes through write_atomically at a path from paths.py. That is what makes each write atomic, skips an unchanged rewrite that would wake a sync, and keeps the XDG layout decided in one module. The rule lived only in those modules' docstrings, so a new write could open a file directly and silently lose all three properties.

CLAUDE.md now states it beside the other guarantees about the written files.

Agent-Name: inbox.problem.fix

Agent-Session: 01a1c30f-5d3d-7298-9b76-b0ae25d4d7cf

Agent-Run: 01a1c30f-1bf9-71aa-85f4-c0a0fd84292e

  • State the fixture and walk docstrings without naming another tool ([d7505ea](http...
Read more

v0.8.3

Choose a tag to compare

@github-actions github-actions released this 18 Oct 05:57

v0.8.3 (2026-10-18)

This release is published under the MIT License.

Bug Fixes

  • resolve: Send a command's full name to that command before any prefix (7531f50)

An incumbent keeps its prefix when a sibling arrives, so a run added after runs took ru got no prefix. run starts with ru, so the prefix walk answered run with runs, and with expanding on, tool run ran tool runs.

named_child tries each child's full name before any prefix is matched, the order argparse uses for abbreviated options. A real command name reaches its command whether or not assignment gave it a prefix. Incumbents keep their prefixes.

The invariant sweep checks through resolve and gains the incumbent case. The README, CLAUDE.md and resolve.py's docstrings give the exact match as the reason a real name expands to itself.

Documentation

  • paths: Give the state directory's real reason and pyselfupdate's real filename (347a823)

pyselfupdate writes autoupdate-.json, not autoupdate.json. The machine is in the name so a synced state directory cannot collide, so the claim that the file must never be replicated was wrong, and it was the stated reason the ledger lives under clisteno/.

The reason is ownership. A tool's state directory belongs to the tool, other libraries write there, and whether it is synced is the tool's decision. The ledger has to be synced, so it gets a directory of the library's own, where one synced folder covers every adopting tool. paths.py, test_paths.py, the README and CLAUDE.md say so.


Detailed Changes: v0.8.2...v0.8.3

v0.8.2

Choose a tag to compare

@github-actions github-actions released this 18 Oct 05:29

v0.8.2 (2026-10-18)

This release is published under the MIT License.

Bug Fixes

  • assign: Keep a pin from taking a sibling's prefix or its name (40f5da0)

Assignment reserved only the ledger's retired prefixes, so two paths recycled a live sequence. A pin naming a prefix a sibling held took it, and the sibling's typed sequence started running the pinned command. A command removed in the same run that a sibling arrived left its prefix free for the arrival, because it was still an assignment rather than a retirement.

Every prefix the ledger records at a level is reserved for its own path. A sibling still in the tree keeps its whole territory, and a path gone from it keeps its string. A pin still moves its own command.

A pin is also checked before the free siblings are assigned, so it could strand one: runs pinned to ru beside a free run left run with no prefix, and typing run reached runs. strands_a_sibling refuses that pin.

The README's precedence paragraph and CLAUDE.md say what a pin may not take.

Documentation

  • Describe resolution as it runs, and give comments their own reasons (6f8eefb)

resolve.py's module docstring claimed spaced prefixes expand. The whole first token is tried as a sequence first, and a token that is one ends resolution there, so j ru reaches jobs and hands back ru. The docstring says so, with examples taken from a tree that resolves them.

Comments that cited a style rule or a personal shell setup carry the reason the rule holds instead: help keeps its renderer's defaults so tools on one stack read alike, help rows bracket optional arguments, and a shell widget on the keystroke path cannot afford a subprocess. The ledger is synced across machines.

test_every_tool_shares_one_state_directory is deleted. The ledger-path assertion in test_state_and_cache_namespace_by_library_not_by_tool already pins the shared clisteno directory.

  • ci: Name the push a racing release run fails on (41ae557)

  • readme: Teach the first run and the assignment model (ad55778)

The README opens on a runnable first use: a small typer tool, the commands that install and run it, and the index it writes. Sections follow for the sequence model, attach, teaching, expanding, the pin exceptions, the files written and the shared format.

Kept: the stenography framing, the byte-identical guarantee, the teaching rows from the hostile fixture, expansion declining when uncertain, the pin file shape, the path table and the cross-language format.

Corrected: a pin outranks the ledger, so a handed-out prefix can move when one is set; assignment alone never changes it. A retired prefix returns to the command that held it. The ledger is meant to be synced rather than synced by the library. The opening example is the demo's verified tool jru instead of an unrunnable tree.

  • resolve: Name the prefixes the one-step example assumes (db77574)

jru reaches jobs run only when run holds ru. With run holding r the sequence is jr, and jru is handed back unexpanded.


Detailed Changes: v0.8.1...v0.8.2

v0.8.1

Choose a tag to compare

@github-actions github-actions released this 18 Oct 02:20

v0.8.1 (2026-10-18)

This release is published under the MIT License.

Bug Fixes

  • resolve: Match a token only up to the command's full name (8afbcf0)

A token matched any child whose prefix it started with, so "update --help" passed as one argument, or "updatefoo", expanded to update and ran it. A token now matches a child only when it starts with the child's prefix and is itself a prefix of the child's name. Anything longer reaches nothing and passes through for the CLI to reject.

Build System

  • Add task setup so a fresh worktree is runnable (2f40362)

A worktree is a clean checkout, so everything gitignored is absent. The virtualenv comes back from uv.lock; .planning has no manifest and is recreated from wherever the primary points.

The primary is derived from --git-common-dir rather than configured, so the target resolves from any worktree and no-ops when run in the primary.

  • Declare the license as an SPDX expression (95c199e)

uv_build warns on every build that a License :: OSI Approved classifier is ambiguous and deprecated under PEP 639. license = "MIT" with license-files replaces both the classifier and the { text = "MIT" } table. The wheel then carries License-Expression and the LICENSE text, under Metadata-Version 2.4.

  • List the tasks by default and give type checking its own task (382abc5)

A bare task lists what the Taskfile offers instead of running the suite. mypy moves out of lint into typecheck, which lint still runs, and fix is renamed format.

  • Take the uv_build range uv init writes under uv 0.12 (8ede9a7)

The range ended below 0.12, so every build under a current uv printed does not contain the current uv version and fetched an older uv_build from PyPI. uv init --package under uv 0.12.2 writes >=0.12.2,<0.13.0, which ends below uv's next minor.

  • Take the version from the release tag (0ba8abe)

python-semantic-release stamped pyproject.toml and pushed a release commit after every merge, so the tag never sat on the merged commit. The version now comes from the tag through hatchling and uv-dynamic-versioning. With no file to stamp, the release tags the merge commit and writes no commit.

uv_build cannot read a dynamic version, so the build backend changes. The wheel holds the same files. The sdist is limited to src/ and the metadata files, as uv_build's was, since it is what PyPI serves. uv.lock drops the root package's version, and the release's re-lock step goes with it.

The publish job already builds from the tag. Its comment now says why that matters: a build anywhere else names the previous release plus a distance.

  • deps: Pin ruff to the fleet toolchain version (d1a72ad)

Dev dependencies now hold ruff at the release the pre-commit hook runs, so a local uv run ruff reports what the hook and CI report.

  • precommit: Resync to forge toolchain 14 (a15f6d9)

  • release: Install the uv release the uv-lock hook pins (5c8d8c2)

The build read pip's newest uv, so each release commit rewrote uv.lock at a format revision the hook, CI and workstations do not write. It now installs the uv-pre-commit rev from .pre-commit-config.yaml.

  • release: Keep feature releases on 0.x under python-semantic-release v10 (5ebbb38)

v10 defaults allow_zero_version to false, and with it the next release of a 0.x project is 1.0.0 whatever its commits say. Measured on a 0.x project with one feat commit: v9.21.2 prints the next minor, v10 prints 1.0.0, and v10 with this key prints the minor again. The shared release workflow still pins v9, so this changes nothing until that pin moves.

  • release: Release a breaking change on 0.x as a minor (37e474e)

1.0 is a compatibility promise, so reaching it is a deliberate edit rather than whatever the next breaking commit does. python-semantic-release defaults major_on_zero to true, so a feat! commit on a 0.x project ships 1.0.0. With the key false it ships the next minor, under both v9.21.2 and v10. Removing the key is how the project reaches 1.0.

Chores

  • Stop ignoring and linking .planning (c8ebea9)

No checkout holds a .planning directory. Worktree setup no longer links one, and the ignore lines matched nothing.

  • Sync the generated CI config to toolchain 20 (fc36b7e)

The stamp moves to 20, carrying generator changes made earlier and never fanned out: one comment names ruff as an installed tool, and the mypy opt-in comment states what decides it rather than what used to.

  • Sync the generated configs to toolchain 18 (1fd0776)

Both stamped files come from the fleet's version declaration: the pre-commit config and the generated workflow. Nothing here is a repo decision.

Stamp 18 carries the refcheck hook at v0.6.0, a codespell exclude widened to go.mod, and — on a private repo — runs-on naming the self-hosted pool with the actionlint config that declares the label.

  • Sync the generated configs to toolchain 19 (bbcadfc)

Both stamped files come from the fleet's version declaration: the pre-commit config and the generated workflow. Nothing here is a repo decision.

Stamp 19 passes --allow-parallel-runners to golangci-lint. A repo with two Go components runs two Lint jobs at once, and on a single self-hosted box the second one dies on the shared cache lock before linting anything.

  • ci: Regenerate from the standard blocks (9388a10)

release.yml runs validate.yml on every push to main, so validate.yml keeps only its pull_request and workflow_call triggers and main is checked once.

  • ci: Regenerate from the standard blocks (719633b)

  • ci: Regenerate from the standard blocks (5f25a89)

  • ci: Regenerate from the standard blocks (cb66fd7)

  • ci: Regenerate the hooks and CI at toolchain stamp 33 (c970991)

  • ci: Regenerate the hooks and CI at toolchain stamp 34 (987c1b6)

  • ci: Regenerate the hooks and CI at toolchain stamp 35 (4271077)

  • ci: Regenerate the hooks and CI at toolchain stamp 38 (ecaef86)

  • ci: Regenerate the hooks and CI at toolchain stamp 40 (0376461)

  • ci: Regenerate the hooks and CI at toolchain stamp 41 (5139bb1)

  • ci: Regenerate the hooks and CI at toolchain stamp 45 (ca40d35)

  • ci: Regenerate the hooks and CI at toolchain stamp 46 (4f4d593)

  • gitignore: Ignore Python bytecode caches (403126c)

Python writes pycache/ beside each module it imports wherever PYTHONPYCACHEPREFIX is unset, so a checkout used without that variable shows every cache directory as untracked.

  • lint: Give the true reason the changelog is excluded from markdownlint (b926508)

No release in this repo writes a CHANGELOG.md. The comment said one was regenerated on every release. The entry stays, so a changelog arriving generated is never linted, and the comment now says that.

  • lint: Ignore the generated CHANGELOG.md (19737aa)

semantic-release rewrites CHANGELOG.md on every release, so markdownlint
--fix normalizing it is undone on the next one and resurfaces as a rebase conflict when a local commit lands on top of the release commit.

  • precommit: D...
Read more

v0.8.0

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:50

v0.8.0 (2026-08-07)

This release is published under the MIT License.

Features

  • Make the short form one stroke, not one word per level (1360b8d)

dectl exgsr, not dectl ex g s r. The prefixes run together with no separator, which is what the design settled on — spaces crept in during implementation and turned one stroke into four words.

Running them together loses the level boundaries, so a string can parse more than one way, and any string that does is by construction the concatenation of two different paths. A duplicate is therefore the whole test, and a sequence that fails it is published by nobody rather than silently won by whichever command sorted first.

A sequence that is already a command name is withheld for the same reason: runs must reach runs, not some deeper path that happens to run together the same way.

Resolution tries the whole sequence before the per-token walk, and has to: exgsr also starts with ex, so the walk alone would answer it with example-pipeline and drop the rest on the floor. The walk still runs for everything else, which is what keeps the long form working.


Detailed Changes: v0.7.1...v0.8.0

v0.7.1

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:36

v0.7.1 (2026-08-07)

This release is published under the MIT License.

Bug Fixes

  • Only rewrite argv when the program is the tool (18dd124)

Enrollment happens at import, and an import is not always a run. pytest collecting a module that calls attach(expanding=True) would have had its own arguments rewritten out from under it, and so would anything else importing the CLI — a REPL, a docs builder, another tool.

The basename of argv[0] has to match the tool before its argv is anyone's business.


Detailed Changes: v0.7.0...v0.7.1

v0.7.0

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:34

v0.7.0 (2026-08-07)

This release is published under the MIT License.

Features

  • Expand a typed sequence before the CLI parses it (bb1dcbe)

attach(app, expanding=True) rewrites argv, so tool ex g s r runs tool example-pipeline glue source-copy run. Without it the teaching hint offers a command the tool rejects, which makes this the half that turns the short form from advice into something that works.

The only surface here that can make a CLI run something other than what was typed, so it declines wherever it is not certain rather than guessing: an unknown token, a retired sequence, and anything following a leading option all pass through for the CLI to answer itself. Expanding to the node reached before a retired sequence would run an ancestor of a command that no longer exists, which is the silent wrong answer retirement exists to prevent.

A real command name expands to itself. A name starts with its own prefix and no sibling's prefix can outmatch it — the invariant assignment maintains is exactly what keeps this from shadowing anything.


Detailed Changes: v0.6.2...v0.7.0

v0.6.2

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:21

v0.6.2 (2026-08-07)

This release is published under the MIT License.

Bug Fixes

  • Key the index by the typed sequence, not the node's prefix (87fc0c4)

A prefix is unique only among siblings, so the flat index handed the shell eleven colliding keys on dectl alone — r alone named five different commands, and l three. Nothing could look anything up in it, which is the one job the file has.

Column one is now every ancestor's prefix followed by the node's own: what a user actually types, and unique by construction. A node under an unassigned parent is dropped rather than given a sequence nothing can reach.


Detailed Changes: v0.6.1...v0.6.2

v0.6.1

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:13

v0.6.1 (2026-08-07)

This release is published under the MIT License.

Bug Fixes

  • Strip rich tags from the index the shell reads (3820d21)

dectl's first real dump exposed it: its summaries carry markup, because Python help is rich's, so the flat index handed the shell rows reading "Glue job [bold]source-copy[/bold] → my-{env}-source-copy-job". That column goes onto the command line, where those are literal characters.

The JSON keeps the tags — a rich-aware renderer wants them — and only the index loses them, so the model stays a faithful record and the rich knowledge sits in one function.

The rule is rich's own: a bracket is a tag when Style.parse accepts what is inside it. That keeps [id], [OPTIONS] and [RUN_ID], which is what a help row means by square brackets and exactly what a blunt strip would have eaten.


Detailed Changes: v0.6.0...v0.6.1

v0.6.0

Choose a tag to compare

@github-actions github-actions released this 07 Aug 01:08

v0.6.0 (2026-08-07)

This release is published under the MIT License.

Documentation

  • Document teaching and the pin file format (fd140df)

"Commands are never modified" was true until teaching shipped, and the pin file had a format nothing described. Both now say what the code does, including that an unusable pin is dropped rather than raised on.

Features

  • Show each command's short form in its parent's help (4117393)

attach(app, teaching=True) writes the assigned prefix into the row a parent renders for each child, so ordinary use trains the fast path. Off by default, because it is the one surface that deliberately changes what a CLI prints.

run (ru) Run the thing, and keep running it until something… runs (runs) List previous runs. destroy Delete everything, permanently and without confirmation.

It writes short_help rather than patching the renderer, which is what keeps it compatible with the settled rule that Python help is rich's with rich's defaults — a library that swapped the formatter would make every tool adopting it the odd one.

Where it writes depends on who built the tree, and getting it wrong fails silently. A click command is the object that runs, so writing to it works. A typer one is not: get_command rebuilds the tree on every call, so the first attempt mutated commands that were then thrown away and the hint never appeared. The durable target is typer's own CommandInfo and TyperInfo. Names come from typer's get_command_name rather than a reimplementation of its rules, with a test that fails if that ever stops lining up with the walked tree.

Parentheses, not brackets — the help rows already use and [id] for required and optional arguments.


Detailed Changes: v0.5.0...v0.6.0