Python
Project host tooling and tests run on Python 3.14.
The repository configuration is authoritative: Ruff formats and lints Python with a 99-column limit, and mypy runs in strict mode. Keep suppressions narrow, next to the exceptional boundary, and explain why the normal rule is unsuitable. Formatting also applies Ruff’s import-order rule to existing import blocks. It does not apply general lint fixes or move imports between runtime, deferred and TYPE_CHECKING blocks.
Interfaces and flow
Section titled “Interfaces and flow”Use the shared directory naming rules: import packages use snake_case, while adjacent resource directories use kebab-case. Resolve the resource directory by its explicit name when it differs from the module stem.
Group modules by the operation or data they own. Keep CLI dispatch, manifest validation, environment setup, build stages and artifact publication distinct. The build entry point shows the order of stages; each stage owns its inputs, effects and result. Import an operation from its owner instead of maintaining alias modules or package-wide re-export lists for old internal import paths.
Import directly from the module that owns the behavior. Use absolute imports across package boundaries; relative imports are limited to sibling modules. Keep a dependency used only in annotations behind TYPE_CHECKING, so that it does not become a runtime dependency; an optional build backend must not become a runtime import for unrelated modes.
Module boundaries also affect delivery. Keep the selected build workspace and check recipes aware of the code they execute, and preserve the independence of files delivered in standalone bundles. Test actual imports and artifacts rather than freezing a list of module filenames.
Use type annotations for maintained interfaces and dataclasses for records with named fields and useful value semantics. Prefer pathlib.Path for filesystem paths and the most specific collection or callable type that describes the boundary.
Keep orchestration readable from the entry point. Give preparation, execution and result collection separate named steps when they have distinct effects, resources or failure modes. Prefer explicit loops and intermediate values when a comprehension or nested expression would hide ordering, mutation or an error path.
Use keyword-only parameters for policy choices and other arguments whose meaning is not obvious at the call site. A flat explicit interface is preferable to a generic options mapping or a long sequence of positional booleans. A lint limit may be suppressed when the parameters represent distinct boundary inputs and a wrapper would only hide them.
For argparse, share an option group only across commands with the same choices, defaults, mutual exclusion and validation. Sharing parser setup must not change accepted arguments, help text or dispatch behavior: keep user-facing help specific to the command and preserve the existing parsed namespace and dispatch semantics.
Reuse and file operations
Section titled “Reuse and file operations”Use the standard library before writing a local algorithm. Stream files through hashlib.file_digest() on the supported host runtime, but do not force that dependency into a separately delivered tool. Use the existing common SHA-256, linker-map and atomic-publication helpers when their contract matches the caller instead of retaining identical local implementations.
Atomic file publication must create the temporary file beside its destination, set the intended final mode, replace only after a complete write, and clean up a failed temporary. The caller chooses whether the content requires flush() and fsync() before replacement: a caller that requires synchronized file contents is not equivalent to one that requires only atomic replacement. Do not weaken an established durability policy merely to share the mechanism.
Keep parsing separate from policy. A shared parser may normalize one format; the caller still owns which symbols, paths, digests or ranges are required and the error presented at its public boundary.
Use the repository’s established failure and output interfaces rather than mixing ad hoc print(), exceptions and exit conversion inside domain helpers. Cleanup must preserve the error that belongs to the failed operation. Message channels and prefixes follow the logging contract.
Text and resources
Section titled “Text and resources”Keep compact generated instructions and their conditional sections beside the code that selects them. Write readable multiline blocks with textwrap.dedent, then substitute values with str.format. Dedent the static block before inserting multiline values so their indentation cannot change the template’s common margin. Keep a shared procedure in one function instead of copying it into each document.
The document renderer owns separators between sections and the final newline. Section content owns its internal line breaks and command indentation; it must not carry hidden blank lines for its neighbors. Do not strip or reflow the finished document to repair its composition.
Keep complete programs, structured templates and independently delivered documents in files beside their owner. Read exact resources as bytes; use explicit substitutions for templates. Resolve resources relative to their owner and include them in the corresponding staged source, causal inputs and archive delivery. A separately delivered script must receive its required resources without importing the full project CLI. Short local settings and dynamic serialization of variable-length structures remain code; multiline syntax alone does not require another file or template engine.
Use pytest as the test backend. Write plain assert statements for values and pytest.raises() for expected errors. Use fixtures for owned resources and cleanup; prefer tmp_path, monkeypatch and capsys when they cover the needed boundary. Parameterize equivalent scenarios with pytest.mark.parametrize, keeping expected results literal and independent of production logic. Test classes group related cases without inheriting from a test framework class.
Follow the shared test contract. Import production modules normally. Use named records and fixtures when they make process state, shell commands or TOML inputs easier to inspect, but keep short decisive values literal in the case. Do not import production constants or algorithms to derive expected data.
Store substantial test documents and executable peers in files owned by the test domain. Keep the preparation, action and independent expected result visible in the test. Preserve interpreter flags, arguments, environment and cleanup when executing a peer from a file.
Read exact input and expected bytes without trimming or normalizing them. An expected document is test-owned: do not render it from the production template. Use parameterized cases with readable identifiers when they share one behavioral contract. Return fixture data directly; use yield when teardown owns a resource. Keep mutable trees and state isolated per case, and preserve timely cleanup of large temporary data even when using tmp_path.
Python tests are divided by the boundary they actually exercise. Keep a unit or host-process result distinct from artifact, public-workflow and hardware evidence, regardless of which test runner invokes it.