Skip to content

livery.workshop

The devkit: what every repository in the livery ecosystem runs. A repository depends on the workshop, and footman mounts it through its project rung: the rendered tasks.py mounts nothing, and every verb below arrives through that dependency.

The extension model

The workspace contract (workshop.toml at the root) lists the workspace's extensions in [workspace] extensions, and each package's contract lists the extensions the package is composed of in its own extensions; a package that lists none holds none. Every extension is one kind: the root's list takes any of them, and a package's list one that composes something in a package. A list's set is the list and every extension it requires, and the installed set is the root's set and every package's set. The workspace's own tests/ directory holds the root's set, so a root lists the language its own tests are written in. No list's order means anything: the installed set mounts in composition order, each extension after the ones it requires and ties alphabetical, and each list is written as its canonical list. Those lists are the whole of discovery: a package installed by accident never changes a repository. The root's list is required; a contract without it refuses at mount and prints the line to add. The base, livery.workshop, is never listed: importing its plugin registers its task surface and then mounts the installed set. The instance always wins last: its own files (CLAUDE.project.md, anything below the plugin line in tasks.py) are seeded once and never rewritten.

Contract keys are kebab-case, at the root and in every package's contract: a key spelled with underscores refuses on read, naming its spelling and the file to rename it in. Every key is declared by the extension that reads it, and a contract holds nothing else: a key no extension declares, a key of an extension no list takes, a value of the wrong type and a value outside its allowed set each refuse on read, naming the file, the key, what the table takes, and the nearest spelling. An extension's keys are taken in the root's contract while the installed set holds it, and in a package's contract while the root's set or the package's own set holds it. While a list names an extension no installed distribution declares, what that extension requires is unknown, so no installed extension's key refuses as one no list takes until fm sync installs it; a key no installed extension declares still refuses. The base declares its own keys the way an extension does, in the contract.toml its package ships beside its code, the keys of extension.toml among them.

The declarations compose into one JSON Schema per contract, and the judge validates a contract against it. fm sync writes the same schemas, one file per contract under .workshop/schema/: workshop.json for the root's contract, package.json for a package's, extension.json for an extension.toml. Each holds the keys of the base and of the extensions of the installed set; a key of an installed extension no list holds stays in it as a key that takes no value and names its extension. The files follow what is installed and listed, and they are written for the checkout alone, never committed. The composed .taplo.toml points Taplo, the language server behind Even Better TOML and other editors' TOML support, at each file by path from the root, so an editor completes and validates a contract as it is typed and refuses what the judge refuses. Each key's doc is its description there, shown when a person hovers the key; every key the base and the listed extensions declare carries one. The schema says what shape a contract has; a rule a schema cannot say stays with the code that reads the key.

The workshop's wheel, livery-workshop, ships the base alone. Every extension of the livery distributions ships in a distribution of its own, named livery-extensions-<name> after the name a contract lists:

Extension Distribution
basedpyright livery-extensions-basedpyright
changelog livery-extensions-changelog
clang-format livery-extensions-clang-format
clang-tidy livery-extensions-clang-tidy
claude livery-extensions-claude
cmake livery-extensions-cmake
conan livery-extensions-conan
coverage livery-extensions-coverage
cpp livery-extensions-cpp
docs livery-extensions-docs
lfs livery-extensions-lfs
mkdocstrings livery-extensions-mkdocstrings
mypy livery-extensions-mypy
nanobind livery-extensions-nanobind
pyrefly livery-extensions-pyrefly
pytest livery-extensions-pytest
python livery-extensions-python
ruff livery-extensions-ruff
ty livery-extensions-ty

A workspace gets an extension by listing it: fm sync installs the distribution of each extension its lists hold, and of each extension those require. An extension's distribution requires the distribution of each extension it requires: conan's requires cpp's, nanobind's requires python's, cpp's and conan's, and mkdocstrings' requires docs'.

An extension is declared by an entry point in the workshop.extensions group, mapping the name a contract lists to the package that ships it. Beside that package sits its extension.toml, which the mount and the contract judge read without importing the extension. The file is a contract like workshop.toml: kebab-case keys, every key judged, and a refusal naming the file, the key, what the table takes and the nearest spelling. Every key is optional to the mount:

  • [extension] description, what the extension does in a sentence or two, which opens its block in the agent's guidance and on the site's development pages; the conformance kit requires it;
  • [extension] api-version, the extension API it was written for, refused at mount when it is not this workshop's;
  • [extension] plugin, the footman plugin carrying its verbs, mounted in composition order;
  • [extension] requires, the extensions it cannot work without, which join every set that holds it, whatever they declare, and come before it in composition order; a list's canonical form leaves them out;
  • [extension] dormant-until, what another extension does for this one by declaring a [for.<this>] table, as a verb: coverage says measures. Until a listed extension contributes such a table, this one is dormant: it registers no step and no job, its plugin still mounts, and fm extensions and fm doctor say what it waits for and which installed extensions would wake it, nothing listed measures; cmake and pytest would. A listing kept for a contributor still to come is a statement of intent, so it is named, never refused;
  • [phases.<phase>], a phase the extension declares, in the grammar the base declares its own in: level, package for a phase run over one package at a time or workspace for one run over the workspace once; gated, whether fm check runs it; after, the phases it follows in the train's order; verb, whether fm <phase> is generated; and keys, the keys the engine running it gives its steps, each with its type. A phase no declaration names refuses naming the declared ones, and two extensions declaring one phase refuse naming both.;
  • [phases.<phase>.<step>], a step the extension adds to a package's lifecycle phase, with the keys every step takes: main, "module:function" in its own package or the tool's words; after, the steps it runs after; and the context keys it provides, each with its type, and reads. The step runs once per package whose set holds the extension, so it names no scope and no extensions. Its deletes names the steps of the base or of an extension it requires that never run for such a package, each "<owner>:<phase>.<step>" to the reason;
  • [queries.<name>], a query the extension declares, in the grammar the base declares its own in: combine, how the answers make one, union, nearest, agreed or a "module:function"; level, package for a question about one package or workspace for one about the workspace; default, the answer while nobody answers; and values, the only answers it takes. Two extensions declaring one query refuse naming both;
  • [queries], the queries the extension answers, each query's name to the "module:function" that answers it, called with the package or the workspace root, or [queries.<name>] value, a literal answer; an answer to a query nobody declares refuses naming the declared ones;
  • [categories], the categories the extension gives the paths of each package whose set holds it, each category to the patterns it takes; a package whose extensions declare categories is answered by them and the base's rules, and its own [categories] wins over both;
  • [fragments."<target>"], a file the extension's code writes, or a directory of them when the target ends in /: render, the "module:function" called with the workspace root, which answers the file's text, or nothing for no file, and for a directory each file's path under it to its text or to the shipped file it links to; local for files that belong to this checkout alone. The fragment lives while the installed set holds the extension, and two extensions writing one path refuse;
  • [toolroom] requires, the tools it runs, its verbs' and its steps', ["docker?>=27"], one of the sites the tool profile reads;
  • [contract.<contract>.<table>], the contract keys it reads, each a table with its types, and its values and doc where it has them;
  • [phases.<phase>.<step>], each step it adds to a phase of the gate, [phases.format.ruff] for fm format.ruff, registered under the listed name, which the gate prints beside each; a step declared enabled = false registers only while the root contract turns it on at the step's own address, [phases.<phase>.<step>] enabled = true;
  • [for.<target>], the same tables, read only while the target is installed and applied only while it is listed, its [for.<target>.queries] answers, its [for.<target>.fragments] files and its [for.<target>.toolroom] requires among them: cmake's [for.coverage] table requires Microsoft's coverage engine on Windows, so a workspace locks it only while it lists coverage. A query is declared at the top level alone. The files the extension ships under content/for/<target>/root/ and content/for/<target>/package/ are delivered while the table applies, as its content/root/ and content/package/ files always are; a directory there for a target the file declares no table for refuses, naming both;
  • [replaces] and [deletes], a shipped file of the base or of an extension it requires, "<owner>:<name>", that its own file of that name replaces or that it deletes, to the reason;
  • [templates.<name>], a template, whose verb fm new.package.<name> creates a package from it: doc, one line saying what a package born from it is; extensions, the extensions such a package lists; and extends, another template whose files the birth writes first. Its files live under content/templates/<name>/ beside the extension.toml. A workspace offers a template while its installed set holds the extension that declares it, and reads it at a birth alone.

A step whose verdict is its tool's exit code is the tool's words, and needs no code:

[phases.format.ruff]
main = ["ruff", "format", "--check", "--force-exclude", "{arguments}", "{paths}"]
fix = ["ruff", "format", "--force-exclude", "{arguments}", "{paths}"]
extensions = ["python"]
tools = ["ruff"]
claims = [{ category = "source", suffixes = [".py", ".pyi"] }]

extensions names the extensions whose packages the step judges: a package whose set, its list and what the list requires, holds one of them. A package that lists no extension holds none, so no such step judges it. A step that names none judges the workspace.

main is the template: the tool's name, as tools names it, and the arguments that judge; fix and safe-fix are the templates that rewrite under --fix and --safe-fix, safe-fix falling back to fix. A template places what the workshop gives it: {paths} stands where the paths the run reaches go, and a template without it runs whole, once with no path, so the tool reads its own configuration; {arguments} stands where the words after -- on the step's verb go, and a template without it takes none. Each stands alone as one word. The workshop splits a long path list into the fewest calls under the command-line limit, runs the tool through its toolroom handle, and a non-zero exit refuses, every call's reason in one refusal. A package step is called from the package's directory with the package's files. env gives each call variables over the run's own, and a word may name a placeholder the workshop answers: {cache}, the step's directory under .workshop/.cache/; {package}, the package a call judges; and {compile-commands}, that package's compilation database, without which the call is skipped. matrix names a placeholder of its own and its values, one call per value in parallel, each its own verdict:

[phases.typecheck.mypy]
main = [
    "mypy", "--platform={platform}", "--cache-dir={cache}/{platform}",
    "{arguments}", "{paths}",
]
matrix = { platform = ["linux", "darwin", "win32"] }

fm explain typecheck.mypy prints the template a step runs and what the workshop puts where {paths} and {arguments} stand. The conformance kit's words-are-answerable clause refuses a placeholder nothing answers, a matrix key no word names, a tool the step does not require, and a package's placeholder in a step that judges the workspace whole.

A step the words cannot say, one whose verdict is not its tool's exit code or whose paths need reshaping first, names the functions that run it instead, main and fix as "module:function" in the extension's own package, each imported when the step runs, and safe-fix a function of its own where the fix has a safe mode. A workspace step in code that declares no inputs narrows by the packages the run reaches, which its code asks scoped_packages for, and one with inputs is selected by them; a step in code that names tools wraps them and takes the words after --. The mount reads each reference from its module's source. A module outside the package, or a name the module does not define at its top level, refuses naming the file and the key before anything runs.

An entry names its extension, either as the string or as a table entry's name. An entry takes no version, ? or scope: an extension's version comes from its wheel, and the lock pins it. A root [phases.<phase>.<step>] table that turns on a step no listed extension declares off refuses in layering.graph, naming the steps declared off.

A footman plugin that declares no extension is never offered as one. The mount registers a [for.<target>] table once both its owner and its target are mounted, so a house with opinions on several languages contributes to each only where the language is listed. Cooperation is greedy: an extension contributes to every target of the installed set it declares a table for. That includes a target listed later, and a target a later release of the extension declares a table for, with no change to the lists. A root entry opts the workspace out with without, the targets the extension contributes nothing to:

[workspace]
extensions = [
    { name = "acme.house", without = ["cpp"] },
    "cpp",
    "python",
]

Here the house, with a table for each language, contributes to python and nothing to cpp, and a language listed later gets its contribution. layering.graph names an entry whose without names a target the extension declares no table for, or one the installed set does not hold, naming the entry and the target. Its --fix writes an entry whose without is empty as the name alone. A package opts out of one step at the step's address in its own contract, [phases.<phase>.<step>] enabled = false. fm extensions prints the base, then each extension in mount order, who requires it, the packages whose sets hold it, its tools, the targets it contributes to (for:), the targets its entry leaves out (without:), whether it is dormant and what would wake it, and each step it declares off with whether the root contract turns it on.

A package's extensions names the extensions it is composed of. Its set is that list and every extension the list requires, transitively, whatever those extensions declare: requires alone composes a package. Two extensions that cannot share a package are refused by the rules of the phase they both add steps to, two providers of one context key or two owners of one executable, never by a rule over the pair. A package writes its set as its canonical list, the minimal one: no extension another listed one requires, in composition order. In that order an extension comes after what it requires; ties go alphabetically. layering.graph names a list in any other form, and its --fix rewrites it. A package's entry is the extension's name alone, with no options.

The root's list is written the same way: its canonical list holds no extension another listed one requires, unless the entry carries a without, since an opt-out has no other place to be written, and comes in composition order. layering.graph names a root list in any other form, and its --fix rewrites it, keeping each entry's comment lines.

The mount takes the installed set in composition order, and every order the workshop reads follows it: the order steps register in, and so the order the gate's rewriters run in under --fix, each also after the steps it names in after; the order a workspace-level query is answered in; the order shipped files compose in; and the order of the guidance. Neither list's order changes any of them. A step of an extension goes into a phase the base, the extension itself or an extension it requires declares, and a step of its [for.<target>] table also into one the target declares; any other refuses at mount, naming the declarer and both ways to write the step. A step's replaces and deletes, and an extension's [replaces] and [deletes], name what the base or an extension it requires declares, and a [for.<target>] step's also what the target declares; the mount refuses any other. Any extension mounts from either list. So an extension's content, tools and distribution belong to the workspace while any list holds it: one that only a package lists joins the dev group, and fm sync installs it. While no installed distribution declares it, the mount names it with the list that brings it. A set is named by its canonical list joined with +, such as cmake+cpp.

fm sync installs a newly listed extension the way the workspace resolves it, before it renders anything else:

  1. It writes the project file alone. Its dev group now names the extension's distribution. This write reads the contracts without judging their keys: until the extension is installed, no declaration says which keys are its, so the root's [python] table would refuse the sync that installs python.
  2. It runs uv sync, which locks and installs through the project file's [tool.uv.sources] and indexes. An extension the workspace sources from a path or from git installs from there, even when an index also offers it.
  3. It continues in a fresh process, which mounts the extension, judges every contract over the installed declarations, and renders every file with it. A key no installed extension declares, such as a misspelt table, refuses there.

When no installed distribution declares the extension after the install, the sync refuses, naming it and the list that brings it. Before that refusal, and when the install fails, the sync puts pyproject.toml, its receipt and uv.lock back as they were.

The base declares its phases in the [phases] section of its contract.toml: sync, clean, build, format, lint, typecheck, typecomplete, examples, drift, provenance, layering, test, stamp, publish, verify, configure and run. The gated ones, build, format, lint, typecheck, typecomplete, examples, drift, provenance, layering and test, are what fm check runs, and each has a verb, fm <phase>, with a sub-task per step. fm sync runs sync once over the workspace, after it installs the tools and before uv sync, and an extension the root lists adds steps to it as one a package lists does. A step there runs once, and one that declares scope = "package" runs once for each package whose set holds an extension its extensions names. A step that runs once and names extensions runs while a package's set holds one of them, and not at all while none does: conan's step makes the one default profile once, however many packages hold conan. A package-level phase, clean, build, stamp, publish, verify or run, runs its steps once per package, and each extension of the package's set may add steps to it, as many as it needs:

[phases.build.bindings]
main = "acme.native._build:bindings"
reads = ["abi"]

[phases.build.wheel]
main = "acme.native._build:wheel"
after = ["build.bindings"]
provides = { wheel = "path" }

An extension whose packages must not run a step another extension of their set adds deletes it, with the reason. The nanobind extension, a distribution of its own, livery-extensions-nanobind, builds a package's platform wheels, so in a set that holds nanobind python's uv build never runs, and neither do the conan steps that would build and publish the recipe the package consumes. Its own stamp step writes the version and raises the floors in both the pyproject and the recipe, since one step of a package provides the files the phase changed, so python's and conan's stamp steps go too:

[phases.stamp.nanobind]
main = "livery.extensions.nanobind._stamp:stamp"
reads = ["version", "floors"]
provides = { changed = "strs" }

[phases.stamp.nanobind.deletes]
"python:stamp.python" = "this step writes the version and the pyproject's floors through python's stamp"
"conan:stamp.conan" = "the recipe names no version, and this step raises its floors through conan"

A package whose set does not hold the deleting extension runs the deleted step as before. A deletion names a step an installed extension or the base declares that runs once per package, and states its reason; any other refuses, naming the file and the step. The walk names each package a registered step skips for a deletion, with the deleting extension and its reason.

Every phase runs through one walk, the gate's phases included: each step is a footman step inside one parallel() block, so footman owns the concurrency, the record, the capture and the cancellation. A step of a package-level phase runs once per package in scope, a step of a workspace-level phase once. Independent steps run concurrently; a step starts once the steps it names in after and the providers of the keys it reads have run, for the same package. A step that fails is the walk's verdict, raised again once every step ran: the steps that depend on it are not run and say so, and the steps that depend on nothing failed still run. A step that needs cleanup on failure does it itself. Each step receives the one PhaseContext: it writes the keys its table provides with provide and reads the ones it reads with read. A value of another type than the declared one (str, int, bool, path, strs, paths or table), and a key the step's table does not declare, refuse naming the step. Two steps providing one key, a key nobody provides, two extensions declaring one step, and an order with no start refuse before any step runs, and layering.graph names them for each package.

A phase's declaration names the keys the engine running it gives its steps, which a step reads like any other and no extension provides. The engine gives each phase its own; a key the phase does not declare, or a value of another type, refuses before any step runs:

Phase Keys the engine gives Key the release train reads back
stamp version (str), the version to write; floors (table), each member released with the package, by its path, to the version it releases at, empty for a member released alone. Each step writes the version into its own manifests and raises there each floor they declare on one of those members, and the base raises the floor of each of the package's [[depends]] edges on one in its workshop.toml changed (strs), the files written
build isolated (bool), the side; configuration (str), the preset: the train builds isolated in release, fm check on the tree in instrumented, and fm run on the tree in debug. epoch (int), the build's source date, from the train; 0 takes the build tool's own dist (path), where the artifacts are
test isolated (bool), true on the train's legs; resolution (str), floor, latest or head; release-dirs (paths), the co-released set's dist/ directories. fm check gives none of them, which is the tree side resolved (table), each distribution the leg installed, to its version
publish version (str) and registry-target (table), the resolved registry's fields, which RegistryTarget.from_table reads back; prebuilt (bool), true when a job of the run built the package and the run collected it into dist/ published (bool), whether anything uploaded
verify version (str), the released version; tree (path), checked out at its receipt tag; interpreter, index and extras (str) exit-code (int), the verification's
run executable (str), the executable to start. The words after -- are the context's arguments, as they are for every step, and the step that starts the executable records its exit code with exit

A phase whose keys hold isolated has two sides: the tree, and the isolated one, from a copy of the sources in a fresh environment. A step declares isolated = true to serve the isolated side alone, isolated = false for the tree alone, and neither for both; the walk runs it on the side the engine gives. isolated on a step of a phase without the key refuses. fm check runs the tree side, so a step serving the isolated side alone is none of the gate's steps: the release train runs it, once per resolution [release] prove lists (Releases). A step of the build phase, which runs once per package and which fm check runs, joins the gate's steps when it serves the tree side: cmake's build.configure and build.compile build each package that holds cmake before its test.ctest runs. The cmake extension is a distribution of its own, livery-extensions-cmake, listed as cmake in a package's extensions. The builds of python, conan and nanobind serve the isolated side alone: each builds what a release publishes, which the gate does not build.

The release train stamps, builds, tests and publishes a package, and fm release.verify verifies a released version, through these phases: the steps the package's extensions add to them. A phase its extensions add no step to refuses the release, naming the phase, and a phase whose steps provide nothing under the key the train reads back refuses, naming the phase and the key. The version the train reads and stamps is its extensions' answer to the current-version query, and a package whose extensions answer none refuses, naming the query. The registry it publishes a package to is its extensions' answer: the one ecosystem their distributions answer names, and the probe of that registry their registry answer gives, which the train polls until an upload is served.

An extension also answers queries, questions the base or another extension declares:

[queries]
public-modules = "acme.native._answers:public_modules"
executables = "acme.native._answers:executables"

[queries.editor-extensions]
value = ["acme.editor"]

A query is declared with the rule that combines its answers, by the base in its contract file and by an extension under [queries.<name>] in its own; a handle, Query("docs.members"), names it and types its answer. A package-level query is asked with a package, answer(package, query), and each extension of the package's set that answers is asked in composition order; a workspace-level one is asked with the workspace root, answer(root, query), and the installed set answers in composition order. The answers combine by the query's rule, and with nobody answering the query's declared default stands, or the rule's answer over nothing. The base declares:

Query Level Answer Combined
public-modules package the modules that declare the public API the union
module-roots package the names other packages reference the code by the union
references package what each source references: its file, its module name, each name with how the source makes the reference, and the names its language's conventions account for the union; a file outside the package, or one two extensions answer for, refuses
version-files package every file stamp's steps write, versions and floors: the release keeps and restores them, and the local act refuses while one has changes of its own the union
current-version package the version the manifests declare one value every answer agrees on
requirements package each required distribution to its constraint the union; a name valued twice refuses
requirement-writers package the functions that write a requirement on a sibling into the manifests, each a RequirementWriter called with the package, the sibling and the floor, and each taking a sibling of its own ecosystem alone the union, and every writer is called; a sibling no writer takes refuses, naming the sibling's set
test-requirements package each distribution the tests require beyond the requirements, to its constraint; a package whose set answers it has a home for its test edges the union; a name valued twice refuses
test-requirement-writers package the functions that write a test requirement on a sibling into the manifests, called as the requirement writers are the union, and every writer is called; a sibling no writer takes refuses, naming the sibling's set
distributions package each released distribution's ecosystem and name the union
registry package the registry the package releases to, as a probe of the versions it serves one value every answer that is not empty agrees on
compile-commands package the build's compilation database the answer of the extension no other answering one requires
executables package the executables fm run starts the union; a name two extensions answer refuses
host-tools package what the host must provide and no store installs, such as a C compiler; fm doctor and fm env.check name each one that does not resolve the union
editor-extensions workspace the marketplace ids the rendered .vscode/extensions.json recommends the union
python.dev-group workspace the lines of the root project file's dev dependency group the union
python.docs-group workspace the lines of the root project file's docs dependency group the union
release-notes workspace the provider that writes each release's notes one answer, the nearest by requires
store.series workspace the state store's series an extension keeps, which the janitor bounds and fm store.ls lists the union
job-built-members workspace each member a job of the release point builds before the wave, its path to the job's name the union; a member two answers give different jobs refuses
checkout-inputs workspace the inputs the checkout step of the rendered GitHub and Gitea workflows passes to the checkout action, each name to its value as the workflow writes it; GitLab's runner checks out by itself and reads none the union; an input two answers give different values refuses, and so does one the step sets from the job's declaration (ref, fetch-depth, fetch-tags, token) or a value that is not a string
ci.fold workspace how the gate job folds a file a check leg's shards each left into the platform leg's one file, by the file's name: a function called with the shards' files in shard order the union; a file two answers fold refuses, and a file nobody folds is red by name in the fold
reaches workspace what a change reaches beyond its own packages and their dependents: functions, each called with the run's Changes, that map each changed path they widen to why and to the paths of the members it reaches; asked while a changed path lies inside a package the union; every member an answer names runs with its dependents, and an answer that raises, or names a path outside the members, runs everything

A name no extension declares refuses with the nearest one; an answer refuses when it is off the query's values. A package-level query is asked of the package's set alone, and a workspace-level one of every extension the workspace mounts, so any extension answers either: nanobind, which composes a package, answers the workspace-level job-built-members.

An extension also answers under [for.<target>.queries], in the same grammar. That answer is asked only while the target is listed and the extension's listing contributes to it, by the rule that registers a [for.<target>] table's steps, so an answer for an unlisted target never runs. An extension that answers one query at its top level and in a [for] table, both asked, answers a union query with every item of both, once each; a query of any other rule refuses, naming both places.

fm run <package>[:<executable>] -- <arguments> starts one of the executables a package's extensions answer under executables, and exits with its exit code. A package with one executable needs no name, and inside a package's directory the package may be left out; completion offers each package:executable. First the gate's build phase runs over the package's dependency closure, dependencies first, on the build phase's tree side in the debug configuration, and passes over each package whose files and dependencies are unchanged since its last good build in this checkout, so a second run with nothing changed starts at once. Then the run phase runs every step the package's set adds to it, except that of the extensions answering executables only the owner's steps run: the step that starts the executable reads the phase's executable key and the context's arguments, and records the exit code with exit, which the verb exits with. An extension that answers executables adds a step to the run phase, or its declaration refuses. The python extension answers with the scripts a package's pyproject.toml names under [project.scripts], and its step starts the one the workspace's environment holds, which fm sync installs.

Each installed template is a verb: fm new.package.<template> <name> creates a package under packages/<name> from the template, and wires it into the workspace. The installed templates are the base's and those of each extension the installed set holds that an installed distribution declares. The workshop makes their verbs when it loads, from the declarations it reads as it mounts the installed set, and makes them again when the installed set changes. fm new.package --help lists each with its doc, and fm new.package alone refuses as any group does, naming them. The birth writes the package-base seeds every package starts from, the base's docs page and what the listed extensions add to it, then the files of each template the born one extends, the template extended first and the born one last; for a path two of them write, the later one wins. The package's contract lists the born template's extensions in their canonical form. Every written file is the workspace's own from then on, and nothing records the template: an extension that needs to know what a package is reads it from the package's own manifests, as python reads its scripts. The templates the livery distributions declare, each available while the extension that declares it is installed. The base declares workshop-extension, which extends python's python-library, so its verb refuses, naming python, until the workspace lists python:

Template Declared by Lists Extends Options
python-library python ["python"] --command
workshop-extension the base ["python"] python-library --app; fixes --command to none
nanobind-module nanobind ["nanobind"] python-library fixes --command to none
cpp-package conan ["cmake", "conan"] --package-type

A template declares its creation options, and its verb takes them as options: fm new.package.<template> <name> --<option>=<answer>. An option is a table under [templates.<name>.options.<option>] in the file that declares the template:

[templates.cpp-package.options.package-type]
doc = "conan's package type, which the recipe's package_type and the CMake target follow"
choices = ["library", "application", "header-library", "static-library", "shared-library"]
default = "library"

Its doc is required, and the verb's --help, completion and the conformance kit's declaration-documented clause read it. It takes either choices, a list of the answers it takes, or a type, one of str, int and bool; a bool option is spelled --<option> and --no-<option>. An option without a default is required. A template that extends another takes the other's options too, and its fixes table gives an answer to one of them, which a birth from it then takes no answer for: workshop-extension writes fixes = { command = "" }, since its one script is the App's. Declaring an option of a template it extends again refuses; fixing one is the way to change it. The declaration also refuses an option named name, the package's name every template's verb takes first, or help, footman's own flag.

Every answer is checked before anything is written. An option the template does not take is an unknown option, a required one without an answer is named, and an answer outside the option's choices or type is refused, naming the option and what it takes. Each option is an ordinary option of the template's verb, with its choices as a Literal, its doc as its help line and its default as its default, so footman's completion manifest lists every template's options and choices as data, and a completion runs no code of the template's.

Each answer renders the template's files as a variable: the option's name with its hyphens as underscores, so --package-type is package_type, and an option without an answer renders its default. A .jinja file that renders to whitespace alone is not written, so a file depends on an answer by wrapping its whole body in {% if command %} and {% endif %}; that is how python-library writes its __main__.py and the test of it only with --command. The answers are not stored: a step that needs one later reads the file the answer wrote, as fm run reads the script from [project.scripts].

  • fm new.package.python-library <name> --command=<script> adds the script <script> to [project.scripts], which runs main() in the package's __main__.py, and a test of it. Without it the package has no script.
  • fm new.package.workshop-extension <name> --app=<script> adds the branded App: _app.py and the script <script>, which runs the workshop with the extension's verbs. Without it the package puts nothing on PATH.
  • fm new.package.cpp-package <name> --package-type=<type> writes conan's package type into the recipe's package_type, and the CMake target that follows from it: a library static or shared as conan's shared option says for library, STATIC or SHARED for static-library and shared-library, an interface library over the header for header-library, and a program with the library its tests link for application.

A creation installs nothing. A template needs its own extensions, those of each template it extends, and the extension that declares each template of that chain, the base aside. A template has its verb while the installed set holds the extension that declares it; for any other template, fm new.package.<template> meets footman's refusal of an unknown task. Every creation, a template's verb and fm ci.scale alike, writes the member through one function, and that birth refuses before it writes anything, in this order:

  1. A template, or a template it extends, that no installed extension declares, while the workspace's lists hold an extension no installed distribution declares yet, refuses naming each such extension and fm sync, which installs it.
  2. A template that extends one no installed extension declares, while the part of its chain that resolves needs an extension the workspace's lists do not hold, refuses naming each with its distribution: list it in [workspace] extensions and run fm sync, then create the package.
  3. A template no installed extension declares refuses, naming the installed templates.
  4. A template whose extends leads back to it, or names a template nobody declares, refuses naming the cycle or the installed templates.
  5. A template that needs an extension the workspace's lists do not hold refuses, naming each with its distribution: list it in [workspace] extensions and run fm sync, then create the package.
  6. A template that needs an extension the lists hold and no installed distribution declares yet refuses, naming each and fm sync.

So a workspace whose root lists the stock list creates a python-library at once, and lists cmake and conan before it creates a cpp-package: until a list holds conan, which declares the template, fm new.package.cpp-package does not exist, and with conan listed and cmake not, it refuses naming cmake. A workspace whose lists hold no python has no fm new.package.python-library, and its fm new.package.workshop-extension, whose template lists python and extends python-library, refuses naming python. Two extensions declaring one template refuse every birth, naming both. A package's contract that writes template refuses: the template is read at the birth alone.

From any directory inside a workspace, a verb resolves the workspace at the directory that holds the root's workshop.toml: a package's own contract below it is passed over, and nothing is written into the package's directory.

An extension's wheel carries its requirements. Each requires target is a dependency of the wheel, so the resolver holds the two to the range the wheel states. A target that ships in the same wheel needs none, since one wheel has one version. The composed dev group lists each stack distribution once. The conformance kit's requirements-in-metadata clause judges the wheel's metadata against the declaration.

The workshop asks two questions about a path, and fm explain <path> prints both answers with the extension that supplied each. Its category says what the file is to its package, source, test, test-support, configuration, and what an extension adds (prose, example, asset, nav). An extension declares a pattern table under [categories] in its extension.toml, and a package takes the tables of the extensions it holds over the base's own table, which names the documentation's paths and calls the rest configuration. The most specific pattern wins. Between patterns of one specificity in two tables, the extension later in composition order wins: an extension wins over the extensions it requires, and of two that do not require one another the later in alphabetical order wins. The base's table comes last. Two patterns of one table at one specificity that claim one path refuse naming both. A package reassigns its own paths in its contract, on this axis alone:

[categories]
vendored = ["docs/assets/vendor/**"]

Its channel says who wrote the file and where to edit it, answered by ranked rules an extension may add to. The workspace root is a unit of its own, with notes/, the site's files and README.md categorised beside its tests, and a src/ at the root refuses in layering.graph, since the root is never a package. A CI job may declare the files its entries read as inputs, the table a step declares: a pull request's run that changed none of them, nor the sources of the extension that contributed the job, skips the job's entries with a line saying so. The docs extension's gate job reads the workspace's docs/, zensical.toml and README.md and each package's pages, nav, assets, examples and generated pages, so a pull request that changes only notes/ skips the site build, and fm explain prints claimed by: gate/docs on a file the build reads. On a contract it also names the schema the contract is judged by, and the owners whose keys that schema holds.

A step also says what its tool needs of the workspace. Its tools reach the tool profile while a package it judges exists, each requirement naming step <name> as its site, so unregistering a step removes its tool. What the base template leaves to the listed extensions, they answer through workspace-level queries: the dev dependency group's tool lines and the docs dependency group's lines are the union of the answers in composition order, and a rendered template reads any workspace-level query by its name, queries['python.dev-group'], an extension's own declared query included: the pytest extension's template reads the words other extensions add to its addopts from queries['python.test.addopts']. The docs extension answers python.docs-group with zensical, the site's builder, and the mkdocstrings extension with its python handler, so a workspace that lists neither composes an empty docs group.

The documentation site is an extension of its own, livery-extensions-docs, listed as docs. It owns the site's assembly, the docs verbs, the docs.config, docs.members and docs.theme queries, and the docs phase every docs verb runs before it assembles the site's config and the deploy phase fm docs.publish runs on the built site, and it arrives through its own task entry point. A package's [docs] table is the extension's whole, so it refuses, naming docs, while the workspace does not list the extension. The base reads no [docs] table and imports no extension, which layering.base-imports-no-extension enforces.

The python API reference is an extension of its own, livery-extensions-mkdocstrings, listed as mkdocstrings; it requires docs. Its step of the docs phase writes each python package's reference into the package's generated tree, a page per module and the api nav block that lists them, and it answers docs.config with the python handler's tables. It also holds the two lint steps that judge the docstrings the reference publishes, lint.docrefs and lint.docstrings. A workspace that does not list it renders no API reference and installs no mkdocstrings.

The coverage extension, livery-extensions-coverage, adds a step to each of the docs extension's two phases in its [for.docs] table, which draws the coverage pages of each package whose [docs] coverage names an htmlcov report.

A step is named by its phase and its own name, test.pytest for the step pytest of the phase test, and that name is everything a person types: a phase's verb runs its steps and each step is a sub-task of it, generated from the registry. fm test runs every step of the test phase and fm test.pytest the one, over the named paths or the workspace. A verb offers exactly the flags its steps read: --fix and --safe-fix where a step can fix, --point where one selects tests by CI point, so fm test --point=nightly runs the nightly's tests and fm test.ctest offers no point at all, and --shard where one runs its share of a sharded check leg. A phase whose verb already exists is served by it: fm provenance is the provenance phase's verb.

A step's own verb hands the tool it wraps the words after --: fm test.pytest packages/strongroom -- -k slow runs that package's suite with pytest's -k slow, and fm lint.ruff -- --statistics gives ruff its flag. The words before -- stay paths. A phase's verb runs several tools, so it refuses words after -- and names the steps' own verbs that take them; fm check refuses them the same way. A step that wraps no tool, such as fm drift.check, refuses them too. A step says it takes them with {arguments} in its template, or by naming tools when it runs code, and its code reads them from the context's arguments: cmake's build.configure names cmake, so fm build.configure -- -DACME_FAST=ON hands cmake its flag.

A step's options are what a package may set in its own contract, each with a type and a default; every step carries enabled, and pytest's test step carries parallel. The step's own table reaches them, and a phase's table reaches every step of the phase:

[phases.typecomplete.basedpyright] # the step, as the gate names it
enabled = false                    # skipped by name in the gate's output

[phases.test]                      # every step of the phase, whatever its tool
parallel = false                   # the suites run under -n 0, each in a run of its own

The deeper table wins key by key: the phase's table, then the step's. An option no step the table reaches declares, a step or phase no registered step has, and a value of the wrong type each refuse, naming the vocabulary.

An extension's steps and categories are judged by the conformance kit, livery.workshop.testing: a Subject names the extension, the sets of extensions to probe it with, each as the list a package writes, and the steps it registers; each clause in CLAUSES returns the violations the subject commits, each naming its clause, and an extension's own suite runs every clause on its subject. The clauses so far: a per-package configuration file has one owner among the steps whose fragments name an extension; a path's category is the most specific rule's, the nearer table winning a tie between tables and two rules of one table never tying; every step a step runs after is registered or declared by an installed extension, and following them never leads back to it; an extension's extension.toml, read under the name its distribution lists it by as the mount reads it, holds only declared keys, each of its type, and every reference in it names a function its module defines; importing a module a reference names registers nothing, which the kit proves by importing each in a process of its own; every task a CI job's entries name is one the extension defines, read from its sources; every category a step's claims name is one the workshop knows, every suffix starting with a dot; the plugin an extension.toml names is an installed footman.tasks entry point; an extension.toml carries an [extension] description, and every verb its plugin defines and every contract key, template, template option, step option and environment variable it declares carries its doc line, each one missing named (declaration-documented); every extension a template lists composes something in a package, unless another it lists requires it, and the set of the template's list holds every extension the template's chain needs (template-composes); a step's fragments render with the kit's probe answers, the composed pyproject.toml still parses, and a per-package file matches its render until a person edits it, when the drift gate names it; and once a step is withdrawn and no other step renders its per-package file for the package's extensions, an unedited copy is removed and an edited one kept; and in the gate's walk over a probe workspace holding one package of each set, with the step bodies recording instead of running, every step of a phase the gate runs that can fix rewrites before any judge starts and is not judged again, every such step names the extension that registered it by the name a workspace lists it under, which the gate prints, and a step with no file to read is named and never started. The workshop's own steps pass the same clauses in its test suite, probed with a package that lists nothing and one listing each installed extension that composes something in a package.

An extension composes something in a package when it, or an extension it requires, declares a step in a package-level phase, an answer to a package-level query or [categories], at its top level or in a [for.<target>] table, or when a step of any installed extension names it in extensions, itself or through a per-package fragment. The installed declarations decide it alone: code that reads a package's set is not seen. Workspace-level steps and answers, contract keys, tools, shipped files, CI jobs, verbs and templates compose nothing in a package. Of the extensions the livery distributions ship, cmake, conan, cpp, nanobind and python compose, and the others do not. For an installed extension no list names, fm doctor names a package's extensions beside [workspace] extensions when it composes.

A package's list takes only an extension that composes something in a package, itself or through an extension it requires. layering.graph names any other entry, says what the extension does instead, such as "its steps judge every package that holds python or conan", and points to [workspace] extensions. Its --fix moves the entry to the root's list with its comment lines and writes both lists in their canonical form. An entry another entry of the list requires is left out of the canonical list instead, and is not moved. A template's list follows the same rule: a template's verb refuses to create a package from a template that lists such an extension, or extends one that does, before it writes anything. Because the proof reads declarations alone, an extension whose only effect on a package lives in its code, such as a workspace answer that varies with which packages list it, is refused in a package's list and is listed in [workspace] extensions instead.

Every extension lives under livery.extensions, a namespace any distribution can add an extension to.

A task's name links to its page through a URL template. A workspace sets one in [workspace] docs-url, which the base's own hook hands to footman: {path} is the task's address joined by slashes, {slug} joined by dashes. That key comes before the docs extension's links under its site-url, and footman's own configured docs-url before both.

An extension contributes CI jobs in its extension.toml, as the docs extension declares the gate point's docs job in [ci.jobs.gate.docs]. A workspace that does not list the extension renders no such job. A contributed job sits before the first job of its point that waits for it, else before the point's verdict job, else last. A table naming a job the point already has, declared, inherited or contributed, joins it instead of adding one; a join's needs join the needs of a job the point has of its own, and a join of a job the point inherits names none. A join of a point's own verdict job may name judges, tasks that judge the run: they run before the job collects the run's rows, and a red one stops the job before the verdict and the stamp, as a red builtin entry does; judges on any other job refuses.

The formatter and the linter are an extension with a distribution of its own, livery-extensions-ruff, listed as ruff. Listed, it registers format.ruff and lint.ruff, which join the format and lint phases, and fm sync writes the root ruff.toml they read, which a bare ruff reads too. A package's own settings go in its own ruff.toml, which extends the root one with extend = "../../ruff.toml"; its per-file ignores go under [lint.extend-per-file-ignores], because a per-file-ignores table of its own replaces the workspace's. Unlisted, the extension registers nothing and writes nothing.

The type checker basedpyright is an extension of its own too, livery-extensions-basedpyright, listed as basedpyright. Listed, it registers typecheck.basedpyright, and fm sync writes the root pyrightconfig.json, which the editor and a bare basedpyright read; the repository's own settings go in its region at the end. It declares typecomplete.basedpyright off, and a root contract with [phases.typecomplete.basedpyright] enabled = true registers it too; it verifies that each package's public API is type-complete. fm new.project lists basedpyright, changelog, coverage, mkdocstrings, pytest, python and ruff, which takes the site's docs in through mkdocstrings. python is there for the workspace's own tests and tasks.py: the root's tests hold the root's set. --extensions names another list, and the birth writes either as its canonical list.

mypy is an extension of its own as well, livery-extensions-mypy, listed as mypy. Listed, it registers typecheck.mypy, which checks linux, darwin and win32 with a cache each under .workshop/.cache/mypy/, and fm sync writes the root mypy.ini, which a bare mypy reads. A new project does not list it.

A package's documentation examples are files under docs/examples/, python files a page shows whole or by named section through the snippets extension: a fence whose one line is the snippet marker followed by the quoted repository-relative path of the file, with pytest extension's examples.pytest step runs each file as one test through the function the python extension answers python.examples.runner with, which starts pytest from the workspace root; a failure reports the example's own file and line. An example is never a test module: pytest's own collector leaves it alone, named or not, so a test_* function in it is code a reader sees and never a test the workspace runs. A run over named files runs the named examples; a whole walk runs the package's directory. A conftest.py beside the examples is the package's setup around them, never an example: it reaches every example item through the example marker, as footman's does to run each inside a captured registry, and naming it runs every example. The example category is claimed by the ruff extension's lint.ruff, for names only, by examples.pytest and by the site; a page's prose reaches the site build and no test, and an example file reaches the examples step and the site.

A step record also owns its configuration. Its fragments, one per rendered file, are what the render writes for it: a [tool.*] table of the root pyproject.toml, composed in step-name order, which a step an extension withdraws takes with it. A tool that reads one file per project gets a file of its own instead, written by its extension under the name the tool looks for: ruff's ruff.toml, pytest's pytest.toml and coverage's .coveragerc. A tool that searches upward from each file, clang-format and clang-tidy in a C or C++ package, gets a managed file where it looks, rendered from the fragment of the record whose extensions the package holds, the first step by name when two have one, and judged by the drift gate, with a .workshop-rendered receipt beside it so a withdrawn step's file goes only when nobody edited it and an edited one is kept as a local override. A package's own lines ride the tool's inheritance, a deeper file with InheritParentConfig. The editor follows the same set: .vscode/settings.json takes each record's lines, and .vscode/extensions.json recommends the extension ids the records carry and nothing else, with a region for the repository's own.

A step record also says which files it judges: its claims, named in categories rather than as globs, each with the rules the step withholds there and the suffixes it reads. A category names what a file is for, not its language, so ruff claims a native package's configuration and reaches its conanfile.py alone, which a scoped gate hands it by name. fm explain prints the steps whose claims reach a file, and the per-file ignores in ruff.toml render from the claims over the tables of the extensions the packages hold, so the docstring rules stop at the tests of every package without a table typed by hand.

An extension's prose, its voice, its standards, its rules, is a set of fragments in sections the base orders: identity, voice, standards, rules, workflow, gate, verbs, compositions, tools. A fragment is a file in the extension's content/fragments/ named <section>.<topic>[.<audience>].md, or a registration with a render that answers each audience from the registries, and two fragments of one name refuse at sync naming both files. fm sync delivers the agent's set flat under .workshop/fragments/, a shipped file byte for byte and an edited copy kept and named, and writes the entry file from it in section order, the repository's own fragments/ last. The gate, verbs, compositions and tools sections render from the registries, so no fragment names a checker by hand. The verbs section lists the verbs of the base, of each plugin no extension carries and of the repository's own tasks file, then gives each extension of the installed set a block read from its declaration: its description, its verbs with the first line of each one's help, its templates, its contract keys and step options with their docs and where each is written, the steps it declares off with the switch that turns each on, and the installed extensions it contributes to and those its root entry leaves out with without, as fm extensions prints them. Listing an extension is the whole step: the next fm sync delivers its block. The compositions section names each set of extensions the packages hold, by the shortest list that composes it, with its packages and the gate phases that judge them.

Each rule over the sources is a step of the layering phase: the base's two (the base importing no extension, and the sibling references, whose fix writes the edges the graph already reaches), and an extension's own, declared as [phases.layering.<step>] with main = "module:function", called with the gate's context. The base's two read each package's references answer, one record per source: the file, the name other code references it by, each name the source references, and the names its language's conventions account for. Each name says whether the source makes the reference at import time or lazily, inside a function or a method body, and whether only a type checker makes it or the source runs without it. A record names a file inside its package, and one extension answers for each file. The python extension answers for python sources from one parse per gate, memoised by the file's path, size and modification time, and its own three steps read the same parse, over the files a narrowed run reaches or every source: private-reaches, which allows a reach into another distribution's private name only where the root contract's [[python.private-reaches]] lists it; runner-terminal, which holds a module that imports the runner to livery.footman.attended(); and declared-imports, which holds each import a package's src makes to the distributions its pyproject.toml declares. The python extension is a distribution of its own, livery-extensions-python, and its page describes each step.

A step's fix runs inside the gate's rewrite, before the judges.

The sibling references' fix writes each edge's requirement before the edge. The package's set answers requirement-writers with its writers, and test-requirement-writers with those of a test edge's requirement, and every one is called. Each takes a sibling of its own ecosystem alone: python writes into pyproject.toml for a sibling that holds python, and conan writes into conanfile.py for a conan package, a sibling that holds conan and whose recipe names a reference. Conan opens the recipe's requires tuple when the recipe declares no requirement. A sibling no writer takes refuses, naming the sibling's set, and nothing is written. A requirement written into a member's pyproject.toml moves the uv lock, so the fix locks again, and the fix's judge reads the contracts as the fix left them.

layering.graph judges each edge of a contract against the package's manifests. A build or runtime edge is a requirement, at the edge's floor, and a requirement on a sibling is an edge. A test edge is a test requirement, at the edge's floor, in a package whose set answers test-requirements; python answers it with the test extra of [project.optional-dependencies], which the release's isolated leg installs the wheel with. The fix of layering.graph writes each test requirement that is missing or names another floor, through the writers the set answers test-requirement-writers with, and locks again when a member's pyproject.toml moved. A test edge in a set that answers no test-requirements, and a tool edge, have no home in a manifest, and nothing judges them there.

Each extension may carry a content/ directory; fm sync delivers it: guidance fragments into .workshop/fragments/, skills and hooks into .claude/ as links (a local override is kept and named), and the managed CLAUDE.md stub whose imports end at the instance's own CLAUDE.project.md.

An extension's fragment can write a root file only while a member needs it. The conan extension, a distribution of its own, livery-extensions-conan, writes conanws.yml at the root while a member's set holds conan, listing each such member by its path, and removes the file with the last of them. Its page describes the file.

A composed file is the extensions', judged byte for byte, and some of them carry lines of your own. Those lines live in a region: a pair of marker comments the composition writes, such as # -- workshop: region tables, yours to edit; the render keeps it -- and # -- workshop: end tables --. fm sync reads what stands between the markers from the committed file and writes it back in place, so it keeps your lines and fm drift still compares the whole file: an edit inside a region is yours, an edit outside it is drift, and a removed marker is drift too. The root pyproject.toml carries a tables region for your own tables, as does the root ruff.toml; the root .gitignore carries a rules region, .vscode/settings.json a settings region, tasks.py a tasks region below the mount, and the changelog extension's cliff.toml in each package an own region. fm explain <file> names a file's regions and their lines. A managed file whose format has no comments keeps your lines as a tail after the lines the render owns.

The variables an extension declares

An extension declares each environment variable it needs in an [env.<NAME>] table of its extension.toml. The conan extension declares its home:

[env.CONAN_HOME]
value = "{place}/conan"
always = true
doc = "conan's cache takes one writer at a time, so each CI job, loop pass and scale fixture keeps a home of its own"

value and doc are required, and always is false when absent. The value takes the placeholder grammar of a step in words and answers one placeholder, {place}: a directory of the variable's own. Every other brace form refuses when the declaration is read, {UPPER} and {env.HOME} among them, naming the form, so a placeholder added later changes the meaning of no declared value. A name a shell cannot export refuses too. A [for.<target>] table declares no variable, and two extensions that declare one variable refuse, naming both.

always makes the extension's value beat one the runner sets for every job, where the job's environment is formed: in setup.sh and in fm env.emit --github. A loop pass and the scale fixture form the environment of what they start the same way. Everywhere else, every fm run among them, the environment wins: a variable it already carries keeps its value, as the cascade's variables do. So a job's later runs keep the value its entry placed, and a nested run keeps the one its parent set.

The workshop sets the variables the extensions of the workspace's installed set declare, and each place names the directory {place} stands for:

Where {place}
every fm run, through the cascade's hook, where the environment carries no value on a CI job, the job's own directory: RUNNER_TEMP on a GitHub or Gitea job, .workshop under CI_PROJECT_DIR on a GitLab one; on a desk, none
setup.sh, for the steps before fm the same directory; the script stops a job whose runner names none
fm env.emit --github, which persists them for a job's later steps RUNNER_TEMP; a job without one refuses
a pass of the loop, fm ci.e2e the directory of the development environment the pass runs on
the scale fixture, fm ci.scale the fixture's directory

A value naming {place} is not set where nothing names a directory, so on a desk conan's own default home stands.

The tools a workspace requires

Six sites declare tool requirements, each in the one requirement grammar, name?>=floor@scope: ruff, ruff>=0.16, dotnet_coverage@windows, tea>=1.1@linux,macos-arm. A scope names platforms (every locked host of one) or host keys, each excluded with a leading !, so tea@!windows-arm is every locked host but one. ? marks a tool optional: the lock takes it where the catalogue can serve it and never refuses it, its entry says optional, and what it left out is printed when the lock is written; fm toolroom.sync names an optional tool its host lacks. The sites: the base, in its contract file's [toolroom] requires, for uv, which makes the venv every step runs in, so a workspace with no package requires it too; the steps that judge a present package, each naming its tools, which is how ruff, pytest and the checkers reach a python workspace; a listed extension, the workspace's or one a package's set holds, as [toolroom] requires in its extension.toml, for the tools it runs, which is how cmake brings cmake and ninja, conan brings conan, and nanobind brings cmake, ninja, conan and the cmake-conan provider, and in a [for.<target>] table, for what it needs while that table applies; a plugin the project mounts through its direct dependencies, as a tuple in a data module its workshop.tools entry point names under the plugin's own name, loaded without the plugin's tasks, which is how forge's dev verbs bring docker?; a package instance, in its workshop.toml under [toolroom] requires, for what its extensions cannot know; and the project, in the root contract's [toolroom] requires, for what belongs to the repository. The root contract's [toolroom] index names where the catalogue is read from, the published index's URL or a directory holding the index or the records that build one. The repository that authors the records reads them directly.

[workspace] hosts names the hosts the workspace supports, in the scope tokens a requirement takes after @: a platform (macos), a host key (linux-arm), and either with ! to remove it. Without the key every host key is supported. The lock covers every supported host, so a requirement without a scope must resolve on all of them. fm sync on another host says so once; in CI, and from fm toolroom.add, it refuses, naming the host and the supported set.

[workspace]
hosts = ["macos", "linux-x64", "windows-x64"]

uv's cache is one per machine and grows with every environment synced, a loop's births included: fm doctor measures it against [workspace] uv-cache-limit, 10G when unset, and fm doctor --fix runs uv cache prune when it is over. A machine that needs a larger cache raises the limit in workshop.toml.

[workspace]
uv-cache-limit = "20G"

fm toolroom.lock resolves every site's requirements against the catalogue and writes toolroom.lock at the root: one version per tool for the whole repository, the newest that satisfies every floor and resolves on every host the tool is required on, refusing by name otherwise. A tool required on some of the locked hosts alone is locked on those, its entry names them, and a scope no locked host matches locks nothing, which the lock says per requirement. fm toolroom.add <requirement> declares a tool at the project site, locks it and materialises it; fm toolroom.lock --upgrade-tool=<tool> moves one entry to the newest eligible version, and every package with it, since no package runs a version of its own.

Entering the environment materialises the bundle the sites require: fm sync supplies every tool locked for this host through the machine's store, skipping one locked for other hosts alone, the downloaded kinds from the catalogue's deployment for this host through [toolroom] sources (folders or URLs in the store's layout, consulted before the origin) and the delegated kinds through their installer, in one of three modes per tool: link puts its entry points in the checkout's .workshop/bin, path its own directories on PATH, none neither, for a tool reached only through a typed handle or its env. A download with paths takes path, one with none and a system tool take none, unless the record or the root contract's [toolroom] modes says otherwise; every installer's kind takes path. A system tool is the machine's own: the store installs nothing for it and holds the copy on PATH to the highest of the record's floor and the sites' floors, naming the site whose floor it is under. A tool named in the root contract's [toolroom] host-allowed may be served by a copy already on the machine: fm sync looks on PATH first, and a copy that satisfies the floor (the requirement's, else the record's minimum, else any version) serves with nothing installed, while one that is absent or below the floor is passed over with a note and the locked version serves. A tool a step reads its verdict from (format, lint, typecheck, typecomplete, test), uv, and a tool an extension writes the release notes with take no allowance, and the lock refuses one by name: a linter that varies by machine makes the gate disagree with CI, and a release's entries must not depend on the machine. The lock's entry carries allow-host, so every checkout agrees on which tools may vary. Each tool leaves a receipt under .workshop/receipts/, this checkout's statement of what it installed: the exact version, the host, the deployment's digest and what reached PATH, and for a host-served tool source: host with the version its copy printed, as the release train's receipt is a release's statement. fm env.emit carries the receipts' paths and variables, and fm env.check names each required tool's receipt and the drift when the lock's deployment has moved under it, a tool with no receipt that still resolves from PATH being named and not a problem. fm enters the environment for itself as well: every invocation applies the same PATH entries and variables to its own process before any task runs, so the locked tools resolve from any shell, an agent's, a CI step's or a bare terminal's, and an entered shell adds only completion. The rendered .vscode/settings.json makes the editor's integrated terminal an entered shell from its first prompt, one profile per platform. A sync whose first act moved the checkout hands the rest to a fresh process on the code now on disk, since the modules it loaded are the old code; a re-run that cannot start is named and the sync continues on the loaded code. A sync whose uv sync moved or removed the distribution of the workshop, or of an extension it mounted, hands the rest over the same way, before anything reads it again: the lock can replace an index's wheel with an editable member at another path, and this process found the workshop's own files or the extension where the wheel was. There a re-run that cannot start refuses, and the next fm sync completes.

The stubs the four type checkers read are materialised too. fm toolroom.restub writes them into typings/ at the root, pyright's default stub path and a search path the rendered configuration hands mypy, ty and pyrefly: one stub per tool the lock holds, at the locked version, as livery.toolroom.stubs modules with livery.toolroom.handles beside them declaring the handles for the installed tools package's index to import, under the namespace package and never inside the tools package's own directory; a tool the workspace does not deploy gets no stub. fm sync, the lock verbs and the entry script write them as well, so a checkout and a CI runner type against the same stubs. The store renders each stub from the locked version's own surface, from the records or the index, so no source holds a stub; a receipt under .workshop/state/ names the lock and the source the last write rendered from, and while both stand nothing is read or written. fm env.check counts them and names their absence.

The task surface

  • fm check: format, lint, four gating type checkers, public-API type-completeness, the tests with per-package coverage floors, and the render gate. Type-completeness covers what each root declares in its __init__; a namespace root, one with no __init__, declares nothing. A public package beneath a root keeps its own import path and is declared in the root's __init__ as well, imported under TYPE_CHECKING and listed in __all__, and the verifier follows the declaration into it; py.typed sits at the distribution's root. Every gate walks the step registry the same way, whole or narrowed, on a machine or on a leg, through the one walk every phase runs through: under --fix every fixer that applies rewrites first, one at a time, then every judge runs in one parallel block, each a footman step, the steps a judge runs after among them, a step that rewrote not judged again; a step whose claims reach no file of its scope is named and no process starts for it. fm check <paths> checks exactly those files, or a directory's: every step whose claims reach one of them runs over them alone, and nothing is recorded as proved; --safe-fix fixes without removing code, the post-edit hook's mode; --point selects a CI point's tests. A named path that is no file or directory in the workspace refuses, since checking nothing there would pass; the steps pass nothing through to a tool, so a tool's own arguments after -- refuse the same way. --shard=<i>of<n> runs one shard of a sharded check leg: a step that declares shard among its flags runs on every shard and runs its share, and every other step runs whole on the first shard alone, so a shard other than the first leaves those steps out and prints one line for each, <phase>.<step>: left to the first shard (this leg is <i>of<n>). On the first shard every step runs and nothing is printed. Inside CI the leg's label ends in the shard, check-ubuntu-latest-3.14-2of3, so the legs pass no flag. A sharded run on a machine records no tree as proved, since a share of the gate ran; a shard outside the form, 0of2, refuses naming it. On a machine the gate is the reflex: it runs what the working tree changed since the nearest tree this checkout's own green gates proved (the one with the fewest changed paths, a green check of the dirty tree included), the packages that delta can influence (their dependents' closure over the [[depends]] graph), and records the working tree as proved, so the tenth commit of a branch pays for what the tenth commit touched and a tree the record already proves runs nothing; --full runs everything. A delta confined to a package's test files runs the package's whole suite and no dependent's, since nothing imports a test, after the package's gate build when its tests run on a build (a C++ package's ctest); a changed conftest or helper, and a source change, run the suite and its dependents'. A suite is never narrowed to the changed test files: the tests a change reaches are more than the ones it edits. A change inside a package reaches further when a listed extension says so through the reaches query: while pytest is listed, python widens a change to a module pytest loads as a plugin to every member pytest runs over. The gate prints one line for each path an answer widens, with why, and runs everything when an answer raises. A machine's test run sets the runner's variables, so a test that reads them is judged here as on the legs. The chain of records rests on a full gate here or on the nearest tree in HEAD's history that CI's record holds: a fresh branch off main starts proved, and one cut before main's own run is green pays for that merge's changes in its first step. A change outside the packages runs everything and roots a new chain, with exceptions. Prose and the site's own files, a file under notes/, a markdown file anywhere, the root docs/ tree, or the root zensical.toml, affect no package, and neither do the root files no package's steps read: the licence, the CI files and the code-owners file, the editor's and the agent's settings, git's own files, setup.sh, the release's member list, overrides/, and the render's receipt. A change that adds or removes a package is that package's: the entries naming it in the root files, and the lock's entries it moves, reach it alone. The workspace's own tests/ directory is a unit of its own, which holds the root's set: a change under it formats, lints, type-checks, and runs those tests alone, by the steps whose extensions the root's set holds, and the record supplies every package's suite. A root whose set holds no python runs none of its own tests, and the test step prints a line saying why. Each workspace step runs when a file it reads changed, and judges those files: lint.doclinks the changed pages, and every page when a file is deleted or moved or a heading is removed; lint.docrefs the cross-references in every docstring the site renders, against the anchors the site renders, when a source, an authored page, a contract, an extension's declaration or a manifest changed; layering.graph only when a contract or a manifest changed; the layering phase's rule steps the changed sources, and every one when the graph changed; drift.check a tracked composed or generated file when it, or what it is made from, changed; provenance.check the changed content files. A step whose own code changed reads everything. A diff that reaches no package and no file a step reads runs nothing. A workspace that declares [ci] affected-legs = true has its CI check legs run that scoped gate, measured by the same rule from CI's own record: from the proved tree nearest the checkout's, or from the merge base with the pull request's base branch when the record proves none. A push to main whose tree no run proved measures the same way from the previous push's tree, and pays the whole gate when the record proves none in reach, since on main the merge base is the push itself. A pull request's run on GitHub tests the merge of its head onto the base branch, so its row names the two commits merged, and the next push's run rebuilds that merge and gates only what changed since it. The workspace steps are selected the same way, and the gate job after a green verdict stamps the tree it proved on the workshop/verified record, naming the check legs that ran, so a later run of the same tree, such as main's run after a squash of a branch on its tip, skips the gate in seconds on every leg whose platform the entry names. An entry proves its tree for those platforms alone: after a pull request's run on one platform, the merge's run ends that platform's leg at once, runs the whole gate on the others, and its stamp names every platform. A narrowed run stamps too when the tree it narrowed against is on the record in full: every package it skipped is byte-identical to that base tree's, so their verdicts carry over, and the row names the base. Without such a base a narrowed run stamps nothing. The release train reads the same record before it waits on main's run.
  • fm <phase> and fm <phase>.<step>: one phase's steps, or one step, generated from the step registry and run over the named paths or the workspace the way fm check <paths> runs them, with nothing recorded as proved; each offers exactly the flags its steps read. fm test.pytest packages/strongroom runs one package's suite, and fm test.pytest packages/strongroom -- -k slow hands pytest the words after --.

  • The check legs run on every runner the contract names, with the newest Python of a derived matrix; the nightly point runs the whole matrix, floor included, so the floor's legs cost runner minutes at night and no pull request time, and a floor-only failure reaches a person the next morning. A declared [ci] python-versions runs at the gate as declared. On a Windows leg of a GitHub-shaped workspace the entry points TEMP and TMP under the runner's own temp: the hosted runners keep the workspace, the uv cache, and that temp on the fast working drive and the system temp on the slow system drive, so the tests' files and the environments they build share the drive with the cache and uv links instead of copying. [ci] windows-temp = "system" leaves the system temp, for a runner without a separate working drive; "runner" asks for the move on any forge.

  • A pull request's check legs run on the runners [ci] pull-request-runners names, the first runner [ci] runners names when the key is absent; a push to main, a dispatch and the nightly run every runner [ci] runners names. A one-runner pull request carries the other legs' coverage rows from main's record, so a package whose floor needs the platform legs' fresh rows on a pull request lists every runner, as the workshop's own repository does. The rendered gate workflow carries both lists as literals and a legs job picks one by the event, computing nothing. A pull request that changes a line only another platform reaches is red by name on a narrowed run: fm submit --every-runner labels it ci:every-runner through the forge, the label starts a run (the workflow runs on labeled), and the legs job takes the full list while the label is there. A person sets the same label on the forge by hand. The repository's configuration creates the label (fm workflow.configure), and the coverage union expects every leg from a labelled pull request.
  • A runner's check leg runs as the shards the contract gives it. [ci] shards maps a runner label to a count, one for a runner it does not name, so shards = { "windows-latest" = 4 } splits the Windows leg into check-windows-latest-3.14-1of4 to 4of4 and leaves every other runner one leg; [ci] pull-request-shards holds the counts for a pull request's legs, judged against its runners, and [ci] shards applies when it is absent; [ci] shards-max caps every count, 4 when absent. The keys hold the counts the check legs' shard list is derived from: livery.workshop.check_shards names the gate's shard legs and livery.workshop.pull_request_shards a pull request's, and a key that names a runner the runner lists do not hold, a count below 1 or above the cap, or one that is not a whole number, refuses naming the key and the runner. A shard's label is its platform leg, check-<os>-<python>, with -<i>of<n> at the end; the platform leg keys every record below the gate job's fold. fm ci.run --shard=<i>of<n> runs one shard of a leg: the shard ends the label every entry reads in WORKSHOP_LEG and the job's display name, check (<os>, <python>, <i>of<n>), which the forge lists the job by, and the check entry runs fm check --shard=<i>of<n>. A leg that runs as one shard of one carries no shard in its label or its display name, and its check entry runs fm check bare. Each shard partitions the run's items, the test files of its test step, by the platform leg's durations rows: longest first, each item into the shard with the least summed seconds, ties by name, an item no row names at the row's median, the first shard's sum starting at the rows' head, the time of the steps only it runs, so every shard of a run computes the same partition and every item lands in exactly one shard. The rendered check job carries the shards as literals. On GitHub and Gitea, while every count is one, its matrix is the os and python lists; when any count is above one it is include entries, one per runner, Python and shard in that order, each {os, python, shard} with the shard spelled <i>of<n>; a runner with one shard has its entry without the shard key, and the one call passes --shard="${{ matrix.shard }}", which reaches that runner's leg empty and runs it as one shard of one. The forge names each job by the entry's values in order, check (windows-latest, 3.14, 2of4), and a one-shard runner's as the unsplit leg, check (ubuntu-latest, 3.14), the name its rows are keyed by. When a pull request's runners or counts differ from every other event's, a legs job holds both matrices as literals, the event picks one, and the check job reads it with fromJSON; both literals take the include shape when any count on either event is above one. On GitLab the one check job runs on the first runner, as that runner's count through parallel: matrix, SHARD taking 1of2 and 2of2, and its call passes --shard="$SHARD"; GitLab reads the first runner's count alone, since its one document serves every event. Each shard leaves what it partitioned in .workshop/fm-shard.json, and its one write carries that record in its timing row. The gate job's ci.fold entry, before any judge reads the run's refs, folds each platform's shards into one leg: it refuses, naming the platform, the shards and what differs, unless every shard the matrix produces left a ref with a row and its record, the shards name one scope, one item set, one list of durations rows read under one bound, no item ran in two shards, and the items they ran are together the set they partitioned. The folded ref is keyed by the platform leg: the timing row with the first shard's tasks, every shard's package sums added and seconds per item merged, named by the platform's own display name, and every other file the shards' entries left folded by the extension that leaves it, through the ci.fold query (the coverage extension concatenates its parts per suite). The shards' refs are dropped once the folded ref is put, so a fold that dies midway is re-run as its own recovery. Below the fold the coverage records, the verified stamp, the speed marks and the janitor's key set see one leg per platform; the forge's rows of the shards stay in the run's metrics file, times alone, and fm ci.timings prints each shard's wall and queue times under the platform's section. A platform none of whose shards left a record partitioned nothing: the gate skipped on every shard, the tree already proved or nothing affected, or no step that reads the shard ran. Its shards fold on their scopes and files alone and the fold says so; one shard with a record beside one without is red by name. Each record names the attempt of the run the shard ran in, as the runner counts them: a rerun of the failed jobs alone keeps the per-run refs the first attempt's passing shards left, and the shard that reruns partitions afresh from the record as it then is, so the fold reads one platform from two attempts with two partitions. Where the partitions differ and the attempts differ, the refusal names the attempts and says to rerun the whole run; fm ci.rerun does that by itself whenever the contract splits a check leg, and says so in one line. A run with no sharded platform says so and folds nothing. On GitLab a job run as parallel: matrix is listed as check: [<i>of<n>], and the job's display name spells the shard that way.
  • A check leg's gate runs profiled, so the leg writes a Chrome trace of every task, step and test it ran, and its timing row is read from that trace; [ci] timing, on unless the contract says otherwise, governs the profiled run and the row. [ci] profile, off unless asked, pushes the trace itself to a channel of its own: refs no sync mirrors and no gate reads, so a checkout pays for a trace only when someone asks for one. fm ci.profile then assembles a whole run into one timeline, and a profiled local command carries the run it caused. See CI profiles for the file, the verbs, and the contract keys. The push is observational: origin refusing it is a printed line and never a leg's verdict.
  • On a GitHub-shaped workspace every job restores the tool store before it enters, under the runner's temp, the working drive, where the checkout and the venv are and where the store's links into the checkout stay links: the data directory the entry places there, keyed by toolroom.lock with the OS and architecture, falling back to the nearest archive under its prefix, so a moved lock restores what is unchanged and saves a fresh archive at the end. A restored store is a tier the store verifies on access, and fm ci.run sweeps it before the save, so the archive carries the trees the tools run from and not the artifacts they were extracted from. uv's cache is placed on the same drive, so the sync links wheels into the venv instead of copying, and is not cached: the wheels it would hold arrive faster from the index than from an archive. A leg that builds native packages also restores conan's home from the same drive, keyed by the recipes with the OS and architecture and falling back under its prefix, so a third-party package from Conan Center is compiled once per key and downloaded from the cache afterwards; the cache is the speed extension and Conan Center the origin, so a miss costs time, never a red leg. The other lanes cache nothing until they have a cache action. Tests are namespaced by their path (pytest's importlib mode, set in the pytest extension's pytest.toml), so two packages may share a test file's name; a helper module in a package's tests/ carries the package's name, and the session refuses to start otherwise.
  • Every CI job keeps each variable an extension declares with a directory of its own, an [env] value naming {place}, in the job's own directory. A declaration with always beats a value the runner sets for its jobs where the entry forms the job's environment, as conan's CONAN_HOME does, and the job's later runs keep it: conan's cache takes one process at a time, and a runner that takes several jobs at once would otherwise have two of them write one cache. On a GitHub or Gitea runner the directory is RUNNER_TEMP, the job's temporary directory, placed by setup.sh github. On a GitLab runner it is .workshop under CI_PROJECT_DIR, the job's checkout, placed by source setup.sh gitlab: GitLab clones each of the jobs that run at the same time into its own path, and git ignores .workshop/. The entry places the variables before its sync builds a native member, and refuses a job whose runner does not set that variable or names a directory that does not exist, naming the declared variable and the extension that declares it.
  • fm start: open the work. An issue number assigns and branches <kind>/<number>-<slug>, a quoted title files the issue first, and <kind>/<slug> starts a branch that belongs to no issue, whose submit closes nothing. Every form branches from a fetched origin/main into a worktree under the runner's home, provisioned and entered when a person is at the terminal: where the shell hook is installed the worktree is entered in that shell, with its environment loaded and nothing to leave, and without the hook a child shell opens there instead (--open=code opens the editor, --open=none prints the path); --no-worktree reuses this checkout.
  • fm commit <type> "<subject>": a conventional commit on a proved tree. It stages the change (--only narrows), derives the scope from the packages the change touches, runs the affected gate first in its fix mode (--no-check skips), validates the subject the way fm submit validates a title, and refuses on main and on a reserved branch. A package whose only changes are the files the engine composes into it stays out of the scope: a template's change renders into every package, and its scope is the template's owner. git commit keeps working.
  • fm integrate: bring origin/main into the branch by merge. A merge rewrites nothing, so every other copy of the branch stays valid, and the squash erases it at landing; a conflict stops with git's own words. When the merge moved uv.lock, the root manifest, or a member's, the verb matches the environment to it and names what moved, so the next gate runs on the merged environment. Every command makes that check before it runs: the venv follows the lock and the manifests, and one that drifted is synced, then the command runs again on the installed code.
  • fm submit: get the branch onto the remote, verified. Its local gate is the reflex; when the chain of this machine's green gates proves HEAD's tree, back to a full gate here or a tree in HEAD's history that CI's record holds, it skips the gate and names the chain, from a record in the checkout's git directory that never leaves the machine. A row proves its tree for a week: the tree id covers the pins, not the machine's tools. --armed lets it land, --fix heals mechanical gate findings into the branch, and the follow classifies the verdict with stable exit codes; a follow that sees the merge from a linked worktree removes the tree and its branch, naming the directory to go to, and keeps a tree holding something the merge did not take. --no-close submits without the close footer, for preparatory work the merge must leave open; a pull request already green when --armed asks is merged directly, since a forge that arms only a blocked pull request refuses. fm submit.merge [pr] lands a green, deliberately-unarmed PR; fm submit.arm [pr] arms one the way --armed does, and fm submit.disarm [pr] takes arming off and leaves the PR open. The three act on this branch's PR, or on the one numbered (123 or #123) from any checkout. A merged PR is done for submit.arm and submit.merge, which say so and succeed, and too late for submit.disarm, which refuses; a PR closed without merging refuses in all three. fm abandon [branch] gives a feature up, this one or a named one, its worktree with it. fm status and fm ci.* stand beside them, all on livery-forge. fm doctor is footman's; the workshop registers its forge and host checks with it, so one verb reports the runner, the forge and the machine.
  • fm drift keeps the composed and generated files byte-identical to what the listed extensions and the contract write, and names fm sync as the remedy; fm new.package.<template> <name> creates a member from an installed template and wires it in.
  • fm release.prepare and fm release.check-tag run the path-tag train (packages/<pkg>/v<semver>); a workshop release also publishes the template snapshot, tagged in lockstep. fm release.verify tests a member's released version from the index against its own tests at the release tag.
  • fm janitor sweeps the runner's directories and the state store: footman's cache, then what the workshop leaves in the data directory (the worktrees of closed issues and merged branches, which fm start sweeps first, the checkout's local branches whose pull request merged, and files and folders no code writes any more), then every series the workshop keeps, in the scope the run has: the checkout's local series on a machine, the remote series too inside CI, where the merge point's gate job runs it after every green run. Windows are enforced, aged rows and orphaned refs go, anything holding work stays and is named, the config directory is reported and never touched, and --dry-run says what would go. The same work runs wherever it is called from: what is safe to remove is decided by the rule that proves it, never by who is watching.
  • fm update brings an instance up to date: floors to the latest released tags, content, render, then the submit flow. Nothing changed means nothing happens.

Where a test runs

A test declares the CI points it runs at. Without a marker it runs at the default points, the gate (a pull request's legs) and the merge (main's run). @pytest.mark.only_at("nightly") runs it at the named points and nowhere else; @pytest.mark.also_at("release") adds points to the default ones. The job runner names the point to every child it spawns, and the workshop's pytest plugin deselects the rest; a local fm check selects for the gate, and fm test --point=nightly selects for a point on demand. A [[ci.schedule]] entry in workshop.toml attaches a task to a point's job; every = "1w" or "2w" runs it on Mondays, or on the Monday of an even ISO week, and any other run of the point skips it naming the day it runs next. On Windows, a test whose child exits with STATUS_CONTROL_C_EXIT, the status a console control event leaves, gets a section in its failure report: the command, the process and its worker, the run, every control event the process itself saw, and every process attached to the console, so one sighting carries what the next reader needs. The nightly point runs the whole check with its own tests selected in, and never skips on the verified record or narrows. fm ci.dispatch --point=nightly starts the nightly now, on main unless --ref names another, and follows the run to its verdict. The run it follows is its own: the one the forge's answer names. A forge whose answer names no run (a GitHub or Gitea server without the run's details) leaves it the one dispatched run of that ref, at the commit origin names for it, that appeared after the dispatch. A run of another ref is never followed. When two such runs appear, as when two dispatches on one ref start together, it refuses and names both. When none appears within a minute, it says so, names the dispatched runs of other refs or commits that did, and exits 14. fm ci.status --point=nightly and fm ci.logs --point=nightly read the newest nightly run by workflow rather than by commit, so a failure only the nightly meets reaches a person through fm. --only names the scheduled tasks a dispatched nightly runs, comma-separated, and the run skips every other entry, the doctor and the check among them, saying so; a name the nightly does not run refuses before anything is dispatched. A rehearsal of a branch runs the loop alone: fm ci.dispatch --point=nightly --ref=<branch> --only=ci.e2e. A tool refresh asked to submit observes nothing off the default branch, since it submits from the default branch alone; the balancer asked to submit does the same. A package contributes a point of its own with [[ci.point]] in its workshop.toml: name (a workflow file name and a job name at once), task, and optionally args, every, runners (the root contract's when absent) and pythons (the newest gate Python when absent). The point runs on the clock and by hand, one job on those runners and Pythons calling the task through fm ci.run, with the job token and nothing more: a permission, a secret or an environment in the table refuses, as does a builtin name, a name two packages claim, a cadence that is not one, or a task no extension mounts. Removing the package removes its workflow: fm drift reports the file as retired and fm sync deletes it. On GitLab the clock is a pipeline schedule, a project setting rather than a line in the pipeline document: fm workflow.configure creates one per point that runs on the clock, named workshop: <point>, and deletes the ones it named for points no longer declared. GitHub and Gitea keep the clock in the workflow file and reconcile nothing. fm ci.dispatch --point=gate starts the gate the same way. A dispatched gate is the full gate: the check verb reads the event and narrows on a pull request alone, and it sets the verified record aside as the nightly does, so a dispatch proves the tree it checks out whatever the record already says. The shell spells one call on every event; nothing passes --full.

Coverage floors

Each package's coverage floor is an extension of its own, livery-extensions-coverage, listed as coverage. A package states its policy in the [coverage] table of its workshop.toml, a table the extension declares, so it refuses, naming coverage, while the workspace does not list the extension. The extension's entry coverage.leg joins each check leg and its judge coverage.union joins the gate job, which judges every package's floor on the union of what every leg measured. The test extensions measure for it, each through its [for.coverage] table: pytest the python suites, cmake the native builds. Its page describes the floors, the record that carries each suite's parts across runs, and the site's coverage pages.

Test speed

The speed marks are off until the contract declares [ci] speed-marks = true: a hosted runner's test time varies by tens of seconds between two runs of one tree, so a mark taken from such runs says nothing about the suite. Declare the key on runners that keep a steady clock. While the key is absent the gate job drops any marks left from before, so a later opt-in starts from the recorded timings alone. On, the gate job judges each check leg's summed test time per package against a mark on the state store. The mark is the median of the leg's last five green runs for the package, recorded once five are seen; it moves down when that median beats it by more than five per cent, so a suite cannot regress slowly. A run over the mark by more than fifteen per cent and twenty seconds warns in the gate job's output, naming the leg's slowest tests and the ones that grew most against their own medians; the second run over in a row on the ubuntu leg is red, and the other legs warn only. A new heavy test is a cost someone chose: fm speed.accept <package> <seconds> --reason=<why> raises the mark, on the ubuntu leg unless --leg names another. The marks are judged on the CI legs alone: a machine's clock is not a leg they were taken on, so fm check on a machine prints each package's summed time and reads no mark, and fm speed.judge is unavailable outside CI. fm ci.timings shows the marks beside the timings.

Balancing the check legs

fm ci.balance reads the same timing rows and proposes how many runners each platform's tests should be split over, so every platform's check leg ends at about the same time. Per platform, a runner and a Python, it takes the newest ten rows whose check jobs ran the full gate and succeeded, folds the shards of one platform into one reading, and takes the medians of four measures: the fixed setup F, every step the forge timed except the call; the summed wall O of the gate steps that are not test steps, which the first shard alone runs; the summed test time S over every package; and the parallelism p the test step reached, S over its wall. The first shard's tests wait about O while those steps run, so its slice is lighter by the O p seconds of tests they hold back, and the shards split S + O p evenly. It predicts the leg's wall at n shards as F + max(O, (S / p + O) / n), the first shard with no tests left at the floor, and the runner seconds as about n F + S / p + O, and prints both for every count up to the cap, [ci] shards-max (4 when absent) or a --max under it. The slowest platform takes the largest count whose every added shard saved at least its own setup; every other platform takes the smallest count whose wall is within 15% of the slowest platform's, or the cap, named. The pull request counts follow the same rule over the pull request's runners when they are fewer than [ci] runners names. The proposal prints as the TOML [ci] shards and [ci] pull-request-shards would hold, with the predicted wall of the slowest leg beside its wall at one shard. A platform with fewer than three such rows keeps its count and is named, and a store that cannot be read prints why and proposes nothing. Without a flag the verb changes nothing.

fm ci.balance --write rewrites [ci] shards, and [ci] pull-request-shards when the pull request runners are fewer, in the root workshop.toml, when a count differs from the contract's and the predicted wall at the proposed counts differs from the wall at the contract's counts by more than 10%: the hysteresis, so two readings that predict about the same wall do not move a count back and forth. The run wall decides, over [ci] runners; when only the pull request's counts differ, the pull request wall does. The rewrite keeps every comment and every other key, writes each table on one line, leaves a count of one out of a table and removes a table that would be empty, and adds a key the contract lacks under a one-line comment; [ci] shards-max is read and never written. It prints what each key becomes and the wall it read, or why nothing was written: no platform with enough rows, no count changed, or a wall that moved less. The workflows carry the counts as literals, so fm sync renders them next, which the last line says.

fm ci.balance --submit lands the same change for a person to merge: from origin's default branch alone, and on another branch it names the branch, writes nothing and exits green, so a nightly dispatched on a branch skips it. A change that is due goes on the day's branch, chore/balance-<date>, started in this checkout from a fetched origin/main; the contract is rewritten, fm sync renders the workflows at the counts, the change is committed as chore(ci): the check legs run as <counts> and submitted unarmed, its gate run by the submit, and the checkout returns to where it was. Origin is asked for the day's branch before anything in the checkout changes: one holding these counts means the day's balance is already submitted, and one holding other counts stops, naming both, for a person to merge or close its pull request first. Nothing due means no branch and no pull request. The pull request is never armed: a count change is merged by hand. This repository's nightly runs it once a day through a [[ci.schedule]] entry, task = "ci.balance" with args = ["--submit"] and once = true, before the tool refresh. A count can also be set by hand in the contract; the next write that is due replaces it.

The runner footprint

fm ci.footprint sums the same timing rows into runner-minutes, so a workspace that inherited a runner matrix sees what it spends. Every job of every run in the window, or of the newest --since runs, is counted on one runner label: a check leg on the runner its job name lists, check (macos-latest, 3.14) or check (windows-latest, 3.14, 2of4), and every other job, the gate job, the docs build and the release jobs, on the first runner [ci] runners names, where the workflow places them. The folded row of a platform's shards is not a job the forge ran and is left out; the shards' own rows carry its minutes. The verb prints the window, its first and last day and its span, one line per runner label and kind with the jobs and the minutes, the total, and the minutes per 30 days from the span, at least one day. A job without a wall time, still running when the gate job collected or never started, is counted apart and priced as nothing. On GitHub, when the repository is public, the same minutes are also priced at GitHub's published rates for the standard runners of a private repository, by the class the label names (ubuntu or linux, windows, macos), a label of no class named as unpriced, with the total and the USD per 30 days: a public repository is not billed for standard runners, and the price says what the matrix would cost one that is. On another forge, or on a private GitHub repository, nothing is priced. An empty window fails naming what fills it: the gate job of a run on the forge writes one row per run.

The state store

Every row the workshop keeps across runs is a row of the state store, which livery-git ships and the workshop builds with its own policy: JSON files on git refs, refs/workshop/* on the remote and refs/workshop-local/* in the checkout's git directory. The workshop declares the series, says who may write (a CI run), which identity every commit carries (the tools') and which variable a published listing travels in; the transport, the snapshots and the janitor are the library's. A default clone or fetch never downloads the remote namespace, no refspec names the local one, and every row carries the schema the store stamped and the time it wrote it. A machine's gate never reaches origin: fm sync and fm start mirror the remote row series the workspace declares, metrics, verified, speed/marks and the listed extensions' own, into refs/workshop-origin/*, one ref per series and never a keyed family, and stamp the fetch with the names; fm check reads those series from the mirror alone, so a hung SSH agent cannot hold the gate. The mirror is what the last sync saw, by design; a checkout the store was never fetched into reads it as unreachable, roots its chain on a full gate, and names the sync. A read inside that gate of any other remote ref, a family's key or a listing of its keys, fails naming the ref and the mirror's scope, never as an absence: a verb that needs a family opens a live snapshot. fm store.ls says which of the two each remote item is. The remote series are written by CI only, fm coverage.accept and fm speed.accept the exceptions; a local run reads them and writes only the local ones, which the checkout's worktrees share and a fresh clone starts without. Only the wire is a git process: every row is read, and every commit written, in the checkout's own object store as bytes, so a remote read is one fetch, a remote write one fetch and one push, a local read or write none, and a series of three hundred rows costs no more processes than one of three. A verb that reads several series takes one snapshot of the remote namespace: one listing of the store's refs and the branches together, then one fetch of the refs the checkout lacks, and every read inside answers from the local object store, so fm store.ls and fm ci.timings cost two round trips. A read inside the snapshot of a ref the verb did not name brings the ref's key group, every sibling at its depth, in one fetch, so a loop over a family's keys costs one round trip; a block opened inside another brings what it names against the shared listing. The job runner takes one snapshot for the whole job and publishes it to the entries it runs, so the gate job lists once for its union, collect, judge, stamp, and janitor. A write keeps its compare-and-swap on the listed sha, its push's own report is its verdict, and it records the sha it pushed for the reads and the entries after it. A check leg writes its per-run ref once, in its last entry, ci.leg: its timing row and every file the leg's other entries left for it, the coverage extension's measured suites among them. The gate job's collect folds the sections its judges left into the run's row, a number per package each, which fm ci.timings renders as a trend, and the job's last entry drops the per-run refs once every leg has completed green, so a red attempt leaves them for its re-run. A point with no gate job (the nightly, the release, a point a package contributes) ends each of its jobs with ci.metrics.record: the job's half from the traces its entries left, the run's row collected from every half present, and the refs dropped by the last job to finish.

series a row is window writer
metrics one run: every job's times, the run's wall, and the sections its judges left, the coverage extension's percentages among them 300 the gate job; each job of a point without one
run/<id>/<leg> a job's half of its timing row, and the files its entries left, the suites the coverage extension measured with the scope it ran among them, until the run's last green job drops it none the leg
durations/<leg> one run on one platform leg: the seconds each item (a test file) took, every phase of every test in it summed over the leg's shards 30 the gate job's collect, after the fold
verified a tree a green gate proved, with its scope and the base it composed on 200 the gate job
coverage/<base>/<leg> the coverage extension's record on one leg, main's or a branch's: one row per suite, its parts in the line format as its last run judged them, at the closure each was measured at, replaced in place, a row it replaced or removed kept a day; each file's fixed facts once under facts/, beside the rows; a branch's goes with the branch none main's gate job at a merge; a branch's own pull request runs
coverage/marks the coverage extension's mark of a package, and who set it 400 the gate job, fm coverage.accept
speed/marks a package's test time mark on one check leg and who set it 400 the gate job, fm speed.accept
gate-record (local) a tree this checkout's fm check proved green 200, 7 days a green local gate
fetched (local) when origin's row series were last mirrored into refs/workshop-origin/*, which series, and how many refs 1 fm sync, fm start
diagnostics (local) the follow classifier's inputs for an unmerged ending 20 every unmerged follow

The durations family is one series per platform leg, check-<os>-<python>, one row per run, {"run": "<id>", "items": {"<item>": <seconds>}, "head": <seconds>}, the newest thirty kept, written by the gate job's collect from each check leg's folded row once the run's metrics file has landed; a series of a leg the matrix no longer produces is the janitor's to drop. The head is the test seconds the first shard's unsplit steps hold back: the summed wall of the gate steps outside the test phase, times the parallelism the other shards' tests reached (the leg's own test step's, unsharded), or the longest such step when no parallelism reads. A shard of that leg reads the newest five rows stamped before the committer time of the commit it checked out and takes the median per item, and the median head, a row without one counting as 0; a row the store stamped at or after that time reaches no shard, so every shard of a run reads the same rows whatever lands while the run is in flight. A series that cannot be read is printed as the reason and the leg runs as one shard of one; an absent series reads as no rows. A shard reads the verified record under the same bound, for the tree its change is measured from and for the skip on a proved tree: a row another run stamps while the shards start counts for all of them or for none, so they measure from one tree and skip together. An unsharded leg reads the whole record.

fm store.ls lists them with what each holds; fm store.show <series> prints a series' rows newest first through the same reader the verdicts use, --key=<leg>,<package> for one series of a family and --json for the rows as they are. fm ci.timings renders the metrics series: per job and metric the latest, p50, and p90 over the window, then the movers. A platform that ran as shards is one section, its folded row, with a line per shard under it giving the shard's wall and queue times from the newest run; the shards' own rows are no sections, and the movers and the speed and coverage sections read the platform legs alone. fm janitor bounds every series in the scope it runs in, windows, ages, and orphans, the remote ones from the merge point's gate job after every green run. The site's deploy phase draws its coverage pages from main's coverage record, the union main's gate judged whatever its legs ran.

Where a test lives

Every pytest under a workshop venv runs apart from the machine's live runner state. footman's pytest plugin points footman's data, cache, and config directories at a fresh temporary home for the session, before the first test and for every child process a test starts, so a test neither reads the developer's config, tokens, worktrees, and caches nor writes into them; a variable the outer environment already set is kept. The one deliberate exception is a live test reading the dev containers' credentials through livery.forge.testing.shared_env_path, which skips without the file. footman's plugin also guards the process-global task registry: a test that leaves tasks there fails at its teardown naming them, and the next test never inherits them. A module first imported under a test's patch gets the original back when the test ends. livery-git's pytest plugin gives every test's git a global config of the session's own, with one identity. The workshop adds one guard to footman's footman.test_guards group, which puts back what an extension mount writes after every test: the listed extensions' steps, the jobs they add to the CI points and join, the task tree a run keeps, and the mount's record. A step one test mounted therefore never judges the changes of a later test on the same worker. The guard also drops the check leg's label from the session's environment, so a test that drives the gate in-process runs as no shard.

The forge lane belongs to livery.forge; the workshop orchestrates local, git, and forge steps and never hands a raw forge verb to a user.