Files
chemenu/docs/reference/commands/distribution-and-versioning.md
torbenandClaude Opus 5.5 f9056c04f7
CI / verify (push) Successful in 6m17s
CI / pwsh (push) Successful in 1m59s
Release / release (push) Successful in 35s
feat: docs/ carries the operator's how-to guides, a configuration reference and the architecture and telemetry explanations carved out of README.md, INSTALL.md, INSTALL-MCP.md and EVALS.md; the last two retired (#190)
Files changed:
- .gitea/workflows/ci.yml
- .gitignore
- .vibe/hooks.toml
- AGENTS.md
- CHANGES.md
- EVALS.md
- INSTALL-MCP.md
- INSTALL.md
- README.md
- VERSION
- docs/dev/development.md
- docs/explanation/README.md
- docs/explanation/architecture.md
- docs/explanation/language-boundaries.md
- docs/explanation/telemetry-and-evaluation.md
- docs/how-to/README.md
- docs/how-to/browse-with-obsidian.md
- docs/how-to/capture-repository-docs.md
- docs/how-to/export-guidelines.md
- docs/how-to/ingest-a-source.md
- docs/how-to/maintain-the-wiki.md
- docs/how-to/query-the-wiki.md
- docs/how-to/run-the-weekly-review.md
- docs/how-to/set-up-the-mcp-server.md
- docs/how-to/trace-and-score-sessions.md
- docs/how-to/troubleshoot.md
- docs/how-to/update-an-instance.md
- docs/reference/README.md
- docs/reference/commands/distribution-and-versioning.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/raw-material-and-uploads.md
- docs/reference/commands/telemetry.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/configuration.md
- instructions/dev/dev-setup.md
- instructions/dev/doc-pull-through.md
- instructions/dev/stack-build/SKILL.md
- instructions/dev/testing-conventions.md
- instructions/dev/version-parts.md
- instructions/setup-instance.md
- instructions/upgrade-instance.md
- reports/CONTRACT.md
- tools/.coveragerc
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/commands/dist_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/commands/eval_cmd.py
- tools/chemenu/commands/git_publish.py
- tools/chemenu/commands/upload_cmd.py
- tools/chemenu/commands/version_cmd.py
- tools/chemenu/evals/__init__.py
- tools/chemenu/evals/scorecard.py
- tools/chemenu/evals/trajectory.py
- tools/chemenu/telemetry/policy.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_git_publish.py
- tools/chemenu/tests/test_instructions_shell.py
- tools/chemenu/tests/test_pipeline_l0.py
- tools/chemenu/toc.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
2026-10-07 05:13:56 +02:00

31 KiB

Distribution and versioning

Exporting, adopting and upgrading an instance, and the version and changelog of the stack itself.

Contents

dist export

Write a contentless, distributable copy of this repo's machinery.

Synopsis

  • wikitool dist export <target> [--dry-run] [--source-repo U] [--source-commit SHA] [--release-url U] [--update-url U]

Options

Arguments:
  target  Directory to write the distribution into. Must not exist, or must be
          empty.  [required]

Options:
  --dry-run              List what would be written, without writing anything.
  --source-repo <str>    Repository this export was built from (recorded in the
                         stamp)
  --source-commit <str>  Commit this export was built from (recorded in the
                         stamp)
  --release-url <str>    Release page this export ships as (recorded in the
                         stamp)
  --update-url <str>     Release feed `version check` should ask (recorded in
                         the stamp)
  -h, --help             Show this message and exit.

Examples

tools/wikitool dist export ../my-wiki --dry-run
tools/wikitool dist export ../my-wiki

Behaviour

  • Writes a contentless, distributable copy of this repo's machinery into an empty or new <target> directory.
  • Ships AGENTS.md/README.md/INSTALL.md with any dist:strip-start...dist:strip-end marker region removed, instructions/ (minus instructions/dev/), types/ (the root: kb page type-specs, their schemas and their subtype templates types/<type>.<value>.md re-keyed as .template, the stack's own verbatim), docs/ verbatim (minus docs/dev/), tools/ (no venv/caches, and not the dev-only test suite tools/chemenu/tests/ with its pytest.ini/.coveragerc), the .github/hooks/+.vibe/ session-tracing config plus .claude/settings.json, kb/CONTRACT.md (no pages, no areas) and VERSION.
  • Ships raw/ and incoming/ as flat roots, each with a .gitkeep and no subdirectories. incoming/.gitkeep is trackable and survives becoming a git repository, so a plain clone gets the directory without any bootstrap step.
  • Ships templates, never the filled files: USER.md.template/SOUL.md.template, kb/CONVENTIONS.md.template, and each collection's contract re-keyed as kb/<name>/COLLECTION.md.template. The filled USER.md/SOUL.md/kb/CONVENTIONS.md/kb/<name>/COLLECTION.md/types/<page-type>.md/types/<page-type>.<value>.md bind their instance; find_leaks refuses a plan carrying one.
  • Writes a generated .wikitool-release.json stamp: version, export date, origin, and a sha256 per exported file - the base a later upgrade compares against.
  • The four origin options only fill stamp fields: export never calls git and cannot discover them.
  • A build and test tool: every release is an export packed as a tarball, and an instance is installed from such a release, never from an export directly.
  • One-way: no command reconstructs a distributed instance into a dev instance - work on the stack in a clone of the origin repo.
  • --dry-run lists every file it would write, and writes nothing.

Properties

  • Changes files: yes
  • Idempotent: yes
  • Atomic: Yes - nothing is written until every file is planned
  • Counts toward the session call budget: yes
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - <target> exists and is not empty, or is not a directory
  • 1 - The tree has no readable VERSION
  • 1 - A licence file is missing from the source tree
  • 1 - The plan would carry this instance's own data (a filled personalization, conventions or page type-spec file)

See also

  • instructions/setup-instance.md - installs a release, which is this export as a tarball
  • wikitool dist upgrade - applies a later export to an existing instance
  • wikitool version show - reads the stamp this writes

dist adopt

Take shipped templates as this instance's own: copy each to its unsuffixed name.

Synopsis

  • wikitool dist adopt [<template>...] [--dry-run]

Options

Arguments:
  templates...  Templates to adopt. Default: every collection contract and page
                type-spec template.

Options:
  --dry-run   List what would be copied, without writing anything.
  -h, --help  Show this message and exit.

Examples

tools/wikitool dist adopt
tools/wikitool dist adopt types/project.md.template types/project.schema.yaml.template
tools/wikitool dist adopt --dry-run

Behaviour

  • Copies <name>.template to <name> byte for byte; the template stays where it is, as the base the next dist upgrade compares against.
  • Without a path: every kb/<collection>/COLLECTION.md.template and every types/*.template (the root: kb page type-specs, their schemas and their subtype templates).
  • With paths: exactly those templates, each of which has to be one of the set above.
  • Never overwrites: a target that already exists is reported as kept and left untouched.
  • Not for kb/CONVENTIONS.md.template or the personalization templates - those carry a sentinel and are filled in, not copied.
  • --dry-run lists what it would copy and keep, and writes nothing.

Properties

  • Changes files: yes
  • Idempotent: yes
  • Atomic: No - files are copied one by one; a re-run completes an interrupted one
  • Counts toward the session call budget: yes
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - A named path does not exist, or is not a collection contract or page type-spec template

See also

  • instructions/setup-instance.md - adopts every template on a fresh instance
  • instructions/upgrade-instance.md - adopts a template a release added
  • wikitool dist export - re-keys these files as .template in the first place

dist upgrade

Apply a stack update dist export produced - the write half of version check.

Synopsis

  • wikitool dist upgrade (<source> | --latest [--expect <version>]) [--dry-run] [--keep-local] [--take-release <path>]... [--prune] [--pre]

Options

Arguments:
  source  An extracted distribution directory, or a release .tar.gz archive - or
          use --latest

Options:
  --latest              Download the release the feed announces as latest
                        instead of naming a <source>
  --expect <str>        With --latest: refuse, before downloading anything,
                        unless the feed's latest release is this version (the
                        one `version notes` was read for)
  --dry-run             Classify and report, without writing anything
  --keep-local          Proceed even with locally changed files - leave each one
                        untouched rather than aborting
  --take-release <str>  Overwrite this locally changed path with the release's
                        version, discarding the local change. Repeatable, and
                        each path must be one this run reports as locally
                        changed. The counterpart to --keep-local, which keeps
                        the change and reports it again on every future upgrade
  --prune               Accepted and ignored: files the new release no longer
                        ships are now deleted by default when unchanged since
                        install
  --pre                 Allow a pre-release (-beta.N) source tree - release.yml
                        never publishes one
  -h, --help            Show this message and exit.

Examples

tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --dry-run
tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz
tools/wikitool dist upgrade ../chemenu-7.1.0.tar.gz --take-release tools/README.md
tools/wikitool dist upgrade --latest --expect 8.0.0 --dry-run

Behaviour

  • Exactly one of <source> and --latest names the release. <source> is an already-fetched export directory or .tar.gz release archive and touches no network: the archive is verified against a sibling .sha256 if one is present (a missing one is a WARN, not a block) and must unpack to exactly one top-level directory - the shape .gitea/workflows/release.yml packs.
  • --latest asks the release feed (update_url of the local stamp, overridable with $WIKITOOL_UPDATE_URL; $WIKITOOL_UPDATE_TOKEN is sent along) which release is latest, checks that version - --expect, a downgrade, a pre-release without --pre, already installed - before any download, then downloads the archive and its .sha256 into a scratch directory removed on every exit. The checksum is mandatory here (a release without one, or an archive that fails it, is an error, not a WARN) and the archive's own VERSION must equal the feed's version. The asset URLs are the feed's own browser_download_url values, and the token reaches an asset download only if it is on the feed's origin. The checksum protects against transfer errors, not against a feed that is itself compromised - authenticity is the trust in the feed's host.
  • --expect <version> (only with --latest) pins the release the feed may announce: a different latest version is refused before anything is downloaded. Pass the version wikitool version notes was read for, in the dry run and in the real run alike.
  • The write set is exactly the new .wikitool-release.json's files block, minus what an export re-seeds from a blank template every time (kb/log.md, raw/.gitkeep) or seeds once and the instance owns from then on (.wikitool-kb.json, CHANGES.md), plus the stamp itself, always rewritten.
  • Every candidate path is classified against the local .wikitool-release.json's recorded digest: unchanged is overwritten silently, absent from the old stamp is created, and locally modified or locally deleted is never silently overwritten.
  • Locally changed files abort the run with the full list; the abort text names the three answers with the command line filled in, and none of them is the default.
  • --keep-local proceeds and leaves every locally changed file untouched. The new stamp is still written whole, recording the release's digest for files that were not written, so a skipped file keeps diverging and is reported again on every later run.
  • --take-release <path> (repeatable) writes the release's version over the named path, discarding the local change, re-creates it if it was locally deleted, and deletes it if the release no longer ships it. The path then matches the stamp and stops being reported.
  • The two are decided per path and compose on one call: without --keep-local, a locally changed path that no --take-release names still aborts the run.
  • A path in the old stamp but not the new one is no longer part of the release. Still unchanged since installation, it is deleted, as silently as an unchanged file is overwritten; changed since, it is locally changed like any other and needs one of the same answers - --take-release deletes it, --keep-local keeps it as the instance's own file, which no later upgrade reports again. Either way it is decided in this run: the new stamp no longer names the path. What the instance owns (kb/log.md, CHANGES.md, .wikitool-kb.json, ...) is never a candidate, and neither is any file the old stamp does not name.
  • A directory left holding nothing - at most a __pycache__/ of *.pyc - once those files are deleted is removed with them, up to but never including the instance root. --prune is accepted and ignored; it used to switch the deletion on.
  • Reports the migration chain the new machinery would owe, but never runs any of it - there is no migrate run.
  • Reports, but does not block on, a crossed compatibility boundary.
  • The local preconditions - VERSION, the release stamp, .wikitool-kb.json, no outstanding migration, a clean working tree - are checked before the source is read. Not being a git repository at all is a WARN, not a refusal.
  • Never touches git - no commit, no push.
  • --dry-run classifies and reports without writing; a pre-release (-beta.N) source needs --pre. With --latest it still downloads and verifies the archive - that is the only way to classify - and removes it again.
  • An interrupted write is not resumed automatically: compare the tree against the printed classification and finish or revert by hand.
  • The closing report names instructions/upgrade-instance.md, which carries the order for everything after the swap and resumes at instructions sync.

Properties

  • Changes files: yes
  • Idempotent: no
  • Atomic: Yes for every refusal - nothing is written. Once writing starts it is a plain sequential file copy with no partial-state cleanup: an interruption mid-copy (killed process, disk full) can leave the tree part-old, part-new
  • Counts toward the session call budget: yes
  • Can reach the network: yes

Exit codes

  • 0 - success
  • 0 - The source's version equals the installed one - a no-op success
  • 1 - Both <source> and --latest, or neither; or --expect without --latest
  • 1 - Local VERSION missing, or no local .wikitool-release.json with a files block
  • 1 - .wikitool-kb.json is missing
  • 1 - A migration is already outstanding against the installed machinery
  • 1 - The working tree is dirty
  • 1 - <source> does not exist, fails its .sha256, or does not unpack to exactly one top-level directory
  • 1 - --latest: the release feed cannot be reached, or answers with something that is not a release
  • 1 - --latest --expect: the feed's latest release is another version than the one expected; nothing was downloaded
  • 1 - --latest: the release publishes no archive or no .sha256 under the expected name; nothing was downloaded
  • 1 - --latest: an asset download fails, or the archive fails its .sha256
  • 1 - --latest: the downloaded archive's VERSION is not the version the feed announced
  • 1 - The source carries no VERSION, .wikitool-release.json or files block
  • 1 - The source's version is older than the installed one, or a pre-release without --pre
  • 1 - A --take-release path this run does not classify as locally changed - the one refusal a --dry-run also raises
  • 1 - Locally changed files that neither --keep-local nor a --take-release answers for; nothing was written

See also

  • wikitool version check - finds out whether an update exists
  • wikitool version notes - the notes of the release --expect should name
  • instructions/upgrade-instance.md - the order after the swap
  • docs/how-to/update-an-instance.md - which release, whether to take it, where the tarball comes from
  • wikitool migrate status - the migrations the report names

version show

Print this instance's stack version and where it came from.

Synopsis

  • wikitool version show [--json]

Options

  --json      Print the version and stamp as JSON
  -h, --help  Show this message and exit.

Examples

tools/wikitool version show
tools/wikitool version show --json

Behaviour

  • Prints VERSION and where this tree came from: "development tree" without a release stamp, otherwise the export date, source commit and repository from .wikitool-release.json, plus the release page when the stamp records one.
  • --json prints the version, its compatibility key, the stamp and the update URL.
  • Bare wikitool version is an alias for this.
  • Read-only and offline; exempt from the Iteration Budget Gate.

Properties

  • Changes files: no
  • Idempotent: yes
  • Atomic: Read-only
  • Counts toward the session call budget: no
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - VERSION is missing or unparseable

See also

  • wikitool version check - asks whether a newer stack exists
  • wikitool version notes - prints a version's release notes

version check

Ask the origin's release feed whether a newer stack exists.

Synopsis

  • wikitool version check [--url U] [--timeout S] [--json]

Options

  --url <str>        Release feed to ask (default: the stamp's, else the built-
                     in origin)
  --timeout <float>  Seconds to wait for the feed  [default: 10.0]
  --json             Print the result as JSON
  -h, --help         Show this message and exit.

Examples

tools/wikitool version check
tools/wikitool version check --json

Behaviour

  • Asks the release feed for its latest release and compares it with VERSION: state is current, update, migration (the step crosses a compatibility boundary) or ahead.
  • The only command whose whole job is the network call - version notes reaches the same feed too, but only as a fallback on a distributed instance, and dist upgrade --latest asks it which release to download.
  • Never reached implicitly from another command (dist upgrade asks only when passed --latest), needs no key, and times out after --timeout seconds (default 10).
  • The feed is --url, else $WIKITOOL_UPDATE_URL, else the release stamp's, else the built-in origin. $WIKITOOL_UPDATE_TOKEN is only needed if that feed is not readable anonymously.
  • For update or migration it prints that applying the release is a separate, manual step (docs/how-to/update-an-instance.md).
  • Read-only; exempt from the Iteration Budget Gate.

Properties

  • Changes files: no
  • Idempotent: yes
  • Atomic: Read-only, no local writes
  • Counts toward the session call budget: no
  • Can reach the network: yes

Exit codes

  • 0 - success
  • 1 - VERSION is missing or unparseable
  • 1 - The feed could not be reached, answered non-JSON, or carried no tag_name

See also

  • wikitool dist upgrade - applies the update this reports
  • wikitool version notes - prints the release notes
  • docs/how-to/update-an-instance.md - what the operator decides before an update

version notes

Print one version's release notes.

Synopsis

  • wikitool version notes [--version X.Y.Z] [--offline] [--url U] [--timeout S]

Options

  --version <str>    Which entry to print (default: this tree's VERSION)
  --offline          Never ask the release feed: on a distributed instance,
                     whose CHANGES.md carries no entry to print, fail with the
                     release page instead of fetching the notes
  --url <str>        Release feed to ask for the fallback (default: the stamp's,
                     as `version check`)
  --timeout <float>  Seconds to wait for the feed  [default: 10.0]
  -h, --help         Show this message and exit.

Examples

tools/wikitool version notes
tools/wikitool version notes --version 7.0.0
tools/wikitool version notes --offline

Behaviour

  • Prints the CHANGES.md entry for --version (default: this tree's VERSION).
  • With no such entry, in a tree with a release stamp (a dist export tree) and without --offline, it prints the release feed's latest release notes instead. A tree without a stamp (a dev checkout) never asks the feed.
  • Only the feed's latest release can be asked for. When that is a different version than requested, stderr names it and the notes are printed anyway - the expected case before an upgrade, where VERSION still names the release being left.
  • stdout carries nothing but the notes; the line naming the feed being asked and the one naming the release that answered go to stderr. release.yml redirects stdout into the file it posts as the release body.
  • --offline never asks the feed and fails with the stamp's release_url instead.
  • Every failure names the stamp's release_url where it has one, so a run that cannot read the notes is still told where they are.
  • Read-only, safe to retry, and exempt from the Iteration Budget Gate.

Properties

  • Changes files: no
  • Idempotent: yes
  • Atomic: Read-only
  • Counts toward the session call budget: no
  • Can reach the network: yes

Exit codes

  • 0 - success
  • 1 - --version is unparseable, VERSION is unreadable when --version is omitted, or CHANGES.md is missing
  • 1 - No entry for the requested version in a tree with no release stamp (a dev checkout)
  • 1 - No entry for the requested version, and --offline was passed
  • 1 - No entry for the requested version, and the feed could not be reached or returned a release with an empty body

See also

  • wikitool version check - asks the same feed whether a newer stack exists
  • wikitool version bump - writes the entry this prints

version bump

Raise or continue the one running candidate between two releases.

Synopsis

  • wikitool version bump --major|--minor|--patch --title "<...>" [--impact high|medium|low] [--breaking "<what breaks>"] [--no-migration "<reason>"] [--migration-required] [--dry-run]

Options

  --major               Bump MAJOR (resets MINOR and PATCH)
  --minor               Bump MINOR (resets PATCH)
  --patch               Bump PATCH
  --title <str>         One-line title for the new/updated CHANGES.md entry
                        [required]
  --breaking <str>      What stops working (recorded in CHANGES.md). Required on
                        the bump that first escalates to a boundary crossing,
                        optional on a later bump of the same crossing candidate
                        - where it joins the reasons already recorded rather
                        than replacing them. Refused on a bump that crosses
                        nothing
  --no-migration <str>  Why the escalation to a boundary crossing needs no
                        content migration (recorded in CHANGES.md)
  --migration-required  Retract this candidate's earlier --no-migration line: a
                        migration is needed after all. Requires a migration
                        document already targeting the new base, and refuses
                        when the entry carries no --no-migration line to
                        retract.
  --impact <str>        high|medium|low - how much this bump matters to a reader
                        of the release notes (default: medium). Grouped into the
                        entry's bump list; `version regrade` corrects it later
                        if the running candidate's own judgment changes.
  --dry-run             Report the change without writing
  -h, --help            Show this message and exit.

Examples

tools/wikitool version bump --patch --title "Fix the lint report path" --impact low
tools/wikitool version bump --minor --title "New command: wikitool review" --dry-run
tools/wikitool version bump --major --title "Rename --gate-file to --remotes-file" --breaking "--gate-file is gone; scripts must pass --remotes-file" --no-migration "no content changes"

Behaviour

  • VERSION gets a -beta.N suffix: one running candidate between two releases, never a fresh number per bump.
  • --major/--minor/--patch is max-wins escalation against the last release (patch < minor < major): a --patch on a MINOR candidate only advances N, and escalation never steps back down.
  • The first bump of a candidate opens its CHANGES.md entry - heading, date, author, and a machine-managed <!-- wikitool:bumps --> list of every --title collected so far, graded by --impact (default medium). Every later bump of the same candidate updates that entry in place: one entry per candidate, not one per bump.
  • The bump list renders grouped under **High/Medium/Low impact** headings, empty groups omitted - except while every bump is medium, where it stays one flat list. version regrade corrects a grade after the fact.
  • Writes the heading, the bump list and the breaking/migration lines; the entry's prose - a summary and one-paragraph ### sections, one per topic - is left to the author.
  • Whenever a required migration document (migrates_to: equal to the candidate's base) exists, every bump writes or refreshes **Migration:** required - <paths>, the documents' paths sorted and comma-separated, in place of any none required line. The two forms never stand side by side.
  • Compatibility follows the leftmost non-zero component of the candidate's base, which for this stack (at 1.0.0 and up) means MAJOR: PATCH is a fix, MINOR a compatible capability, MAJOR a version that is not a drop-in replacement - any hand-work on update, or a downgrade that no longer works. Whether content must be migrated is a second, independent question.
  • The bump that first escalates a candidate past the boundary requires --breaking "<what stops working>" and, on top of it, a migration document targeting the candidate's base or --no-migration "<reason>". Both are anchored just above the bump list, persist over later bumps of the same candidate without being repeated, and are refused on a bump that crosses nothing at all.
  • On a later crossing of the same candidate, a further --breaking joins the reasons already recorded (flat on the marker line while there is one, bullets under a bare marker from the second on; repeating a reason verbatim is a no-op), while a further --no-migration replaces the single migration line.
  • --migration-required replaces the running candidate's --no-migration line with the required line; it needs a required migration document already targeting the new base. Nothing retracts a recorded --breaking reason.
  • Enforces that a crossing documents itself, never that the part was chosen correctly.
  • Not idempotent: every successful run escalates or continues the candidate again.
  • --dry-run reports the step without writing.

Properties

  • Changes files: yes
  • Idempotent: no
  • Atomic: No - VERSION then CHANGES.md
  • Counts toward the session call budget: yes
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - Not exactly one of --major/--minor/--patch, an empty --title, or an unknown --impact
  • 1 - VERSION or CHANGES.md is missing, or VERSION and the changelog's newest entry name different versions
  • 1 - An escalation to a boundary crossing without --breaking, or with neither a migration document targeting the new base nor --no-migration
  • 1 - --breaking or --no-migration on a bump that crosses nothing
  • 1 - --no-migration while a required migration document targets the new base
  • 1 - --migration-required combined with --no-migration, on a bump with no running candidate, with no --no-migration line to replace, or without a required migration document already targeting the new base

See also

  • wikitool version regrade - corrects an --impact grade
  • wikitool version release - fixes the candidate into a release
  • instructions/migrate-corpus.md - how a migration document is written

version regrade

List the running candidate's bump titles with their impact grade, or change one or more of them.

Synopsis

  • wikitool version regrade [INDICES...] [--impact high|medium|low]

Options

Arguments:
  indices...  1-based positions in the rendered bump list to regrade (see the
              bare listing). Omit to just list.

Options:
  --impact <str>  high|medium|low - required together with indices
  -h, --help      Show this message and exit.

Examples

tools/wikitool version regrade
tools/wikitool version regrade 3 7 --impact high

Behaviour

  • Without arguments: lists the running candidate's bump titles with their grade, numbered by 1-based position in the rendered list (High before Medium before Low, chronological within a grade). Read-only and exempt from the Iteration Budget Gate.
  • With indices and --impact: sets the grade of every named position in one call, all resolved against a single read of the current list - version regrade 3 7 --impact high grades what is at 3 and 7 now, not 7 after 3 has moved. Writes CHANGES.md and is counted by the Iteration Budget Gate.
  • The correction path for an --impact grade judged at bump time.
  • Touches only the topmost entry's bump list - never VERSION, never any other part of CHANGES.md.
  • A write is not idempotent against a changed list: after a first success, the same indices may name different bumps.

Properties

  • Changes files: yes
  • Idempotent: no
  • Atomic: No - CHANGES.md only, and only when indices are given
  • Counts toward the session call budget: only when called with arguments
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - VERSION or CHANGES.md is missing, VERSION and the changelog's newest entry name different versions, or the topmost entry has no bump list
  • 1 - An index outside the rendered list's range, indices given without --impact, or an unknown --impact

See also

  • wikitool version bump - sets the grade in the first place
  • wikitool version release - refuses without a summary above this list

version release

Fix the running candidate: strip VERSION's -beta.N suffix and close its CHANGES.md entry.

Synopsis

  • wikitool version release [--title "<...>"] [--dry-run]

Options

  --title <str>  Replace the entry's heading title (default: the last bump's)
  --dry-run      Report the change without writing
  -h, --help     Show this message and exit.

Examples

tools/wikitool version release --dry-run
tools/wikitool version release --title "Command records rewritten for agents"

Behaviour

  • Strips VERSION's -beta.N suffix - the candidate's base becomes the release - and closes the candidate's CHANGES.md entry.
  • Without --title the heading keeps whichever bump last set it; --title replaces it - the normal case for a candidate that collected several bumps, whose entry wants a summarising heading rather than the most recent one.
  • Leaves the entry's machine-managed bump list untouched, as the record of what happened.
  • From two bumps on, requires a summary paragraph (at least 200 non-whitespace characters) between the bump list and the first ### section heading. A candidate with exactly one bump is exempt, since there its own paragraph already is the summary. --dry-run runs this check too.
  • Refuses an entry that would exceed its budget once released: at most 32 000 bytes (UTF-8) as version notes prints it, and every ### section exactly one paragraph of at most 1 000 bytes, heading line excluded. The same check as docs verify, run on the released heading; --dry-run runs it too.
  • Commits nothing and pushes nothing. The following publish moves VERSION onto main, which release.yml reacts to.
  • Not idempotent: a second run fails once the suffix is gone.

Properties

  • Changes files: yes
  • Idempotent: no
  • Atomic: No - VERSION then CHANGES.md
  • Counts toward the session call budget: yes
  • Can reach the network: no

Exit codes

  • 0 - success
  • 1 - VERSION is already a release - there is no running candidate to fix
  • 1 - VERSION or CHANGES.md is missing, or VERSION and the changelog's newest entry name different versions
  • 1 - Two or more bumps and no summary paragraph above the ### sections
  • 1 - The entry is over 32 000 bytes, or a ### section has more than one paragraph or a paragraph over 1 000 bytes - the error names each with its size

See also

  • wikitool version bump - opens and continues the candidate
  • wikitool version regrade - shows the bump list the summary sits under
  • wikitool publish - moves the released VERSION onto main