Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.
# Drift contracts — declared review obligations between code, docs, and tests.
#
# A contract says: when these trigger files change, these review targets must be
# re-examined against the change, and the examination must be recorded with
# `make drift-ack CONTRACT=<id> RATIONALE="<verdict>: …"`. `make drift-check` gates the local
# `make agent-check` and `make check` aggregates, and `Lint (drift-contracts)` is a
# required status check on `dev` and `main`. See docs/contribute/drift-contracts.md
# for the full workflow.
#
# Keep this manifest small: every contract here must earn its friction. Anything
# mechanizable (regenerate-and-diff, referential integrity) belongs in a derived
# check (check-config-sync, check-mthds-schema, …), never in a review contract.
version = 1
[contracts.config-docs]
description = """
User-facing configuration docs must track the config model and the shipped defaults, and a change \
to that model must be answered in the migration ledgers — including the domain narrowing no \
fingerprint can see, because it lives in a validator rather than in an annotation. The four live \
sites: KitConfig._validate_targets, DryRunConfig.validate_image_urls, \
ImgGenConfig.validate_quality_mapping, LLMConfig.validate_effort_to_budget_mapping.\
"""
# The config model tree is rooted in system/configuration/ but several documented
# submodels are defined in their own packages — they trigger too, and so does the log-level
# enum, whose members are the values the logging docs list.
triggers = [
"pipelex/system/configuration/**/*.py",
"pipelex/system/telemetry/telemetry_config.py",
"pipelex/cogt/config_cogt.py",
"pipelex/cogt/img_gen/img_gen_job_components.py",
"pipelex/graph/graph_config.py",
"pipelex/language/mthds_config.py",
"pipelex/methods/methods_config.py",
"pipelex/tools/aws/aws_config.py",
"pipelex/tools/log/log_config.py",
"pipelex/tools/log/log_levels.py",
"pipelex/tools/network/network_config.py",
"pipelex/tools/secrets/secrets_config.py",
"pipelex/tools/storage/storage_config.py",
"pipelex/pipelex.toml",
]
# Three kinds of target, not one. The docs are the user-facing prose. The ledgers are where a
# shape change is answered, and the two source files are there because they hold the four
# validators above: a validator that narrows a value domain is semantic residue the fingerprint
# projection cannot record, so the coverage gate calls the change additive and the review list is
# the only place the obligation can land. Reviewing them means asking, of the change that opened
# this contract, whether it narrowed a domain, and if it did, whether an `unsafe` entry carrying
# `declared_narrowed_paths` is owed. See docs/migration-ledger.md § The fingerprint.
#
# Deliberately absent: pipelex/migration/goldens/. They are generator output (`make umig`), which
# a review list must never carry, and their staleness is already a derived check —
# `check-migration-schemas` fails on a head golden the models have moved past.
review = [
"docs/configuration/**/*.md",
"pipelex/migration/ledgers/",
"pipelex/system/configuration/configs.py",
"pipelex/cogt/config_cogt.py",
]
# `make tb` only. `check-ledger` and `check-migration-schemas` already gate `make check` and CI,
# so re-running them here would add the unstaged-file hard error without adding a guarantee.
verify_commands = ["make tb"]
[contracts.cli-docs]
description = "CLI docs and the agent-CLI contract doc must track the CLI surface."
triggers = [
"pipelex/cli/**/*.py",
]
exclude = [
"pipelex/cli/dev_cli/**",
]
review = [
"docs/tools/cli/",
"pipelex/cli/agent_cli/CLAUDE.md",
]
verify_commands = []
[contracts.keyword-only-convention]
description = "The keyword-only-arguments doc is the convention's specification and must track the guard's behavior."
triggers = [
"pipelex/cli/dev_cli/commands/keyword_only_guard.py",
]
review = [
"docs/contribute/keyword-only-arguments.md",
]
verify_commands = []
[contracts.hub-layering-convention]
description = "The hub-layering doc is the boundary's specification and must track the guard and the two hubs."
# The guard owns the rule (declared kernel layer, violation kinds, carve-outs); the two hub
# modules own the symbol partition the doc tabulates accessor by accessor. A symbol added to or
# moved between them silently falsifies those tables, which is the staleness this contract exists
# to catch. No verify command: `check-hub-layering` already gates `make check` and CI, so re-running
# it here would only add the unstaged-file hard error without adding a guarantee.
triggers = [
"pipelex/cli/dev_cli/commands/hub_layering_guard.py",
"pipelex/runtime_hub.py",
"pipelex/interpreter_hub.py",
]
review = [
"docs/contribute/hub-layering.md",
]
verify_commands = []
[contracts.pipelex-kernel-docs]
description = "The pipelex-kernel doc is the kernel's specification for programmatic callers and must track the kernel surface."
# The page tabulates the surface module by module (every entry point a caller imports) and states
# what each of the four layering gates covers. A kernel function added, renamed or moved silently
# falsifies the first table; a change to the boot-contract script's coverage silently falsifies the
# second. Neither is mechanizable — "does this prose still describe the surface" is a judgement — so
# it is a review obligation rather than a derived check. No verify command: the gates the page
# describes already run in `make check` and CI.
triggers = [
"pipelex/kernel/**/*.py",
"tests/unit/pipelex/kernel/test_kernel_boot_contract.py",
]
review = [
"docs/under-the-hood/pipelex-kernel.md",
]
verify_commands = []
[contracts.log-call-convention]
description = "The log-calls doc is the log-call guard's specification and its command's reference, and must track the guard's behavior and the command's options and output."
# The page states what the guard reads (the scanned trees, every way a module reaches the facade, a
# message and its titles), each rule it refuses a call under, how a name is resolved through the
# bindings and control flow of its scope, what counts as a Rich tag, and the baseline's key,
# signature and shrink-only comparison. Under "Running it" it also states what each of the
# command's options does and what a pass and a failure print, which the command module decides. A
# reading, a rule or a signature changed in the guard, or an option or an output changed in the
# command, silently falsifies the page a contributor converts a call by, which is the staleness
# this contract exists to catch. No verify command: `check-log-calls` already gates `make check`,
# `make agent-check` and CI, so re-running it here would only add the unstaged-file hard error
# without adding a guarantee.
triggers = [
"pipelex/cli/dev_cli/commands/log_call_guard.py",
"pipelex/cli/dev_cli/commands/check_log_calls_cmd.py",
]
review = [
"docs/contribute/log-calls.md",
]
verify_commands = []
[contracts.logging-docs]
description = "The logging doc restates the console's field rules and the handled-exception fields, the log-sink page summarises what the console renders, and both must track the modules that decide them."
# The page restates, rule by rule, what the modules decide: the style map (`FIELD_STYLES`) and
# the fields it colours, the cut lengths (`FIELD_VALUE_MAX_LENGTH` and the generous ones in
# `FIELD_MAX_LENGTHS`), the field names whose value is cut at its start (`LEFT_CUT_FIELD_SUFFIXES`,
# `LEFT_CUT_FIELDS`), in `console_fields.py`; the handled-exception fields and their arguments, in
# `error_fields.py`; and, in `pydantic_utils.py`, where `error_fields` writes a `ValidationError`
# through `describe_exception_without_input`, when a pydantic message is kept rather than its error
# type (`SCHEMA_CONTEXT_KEYS`, `refusal_reason_without_input`) and how a location is written
# (`located_validation_errors`: what the schema names, `<key>` for the rest, an authored document's
# as pydantic gives it). A name added to one of
# those sets, or a length moved, silently falsifies a sentence quantifying over it, which is the
# staleness this contract exists to catch. The log-sink plugins page describes the `console` sink
# in its table of built-in sinks and again where it explains why that sink is the default, and
# both passages name what a terminal shows of a record, the fields after the message, their
# colours and the advice line, so a change to what the console renders is reviewed there too, not
# only on the logging page it links to. The field-vocabulary table on the logging page stays
# outside any contract on purpose: its entries come from call sites everywhere, which no trigger
# list could name, and a field joins the table in the change that first logs it. No verify
# command: no gate checks these rules apart from the modules' own tests, which `make agent-test`
# and CI already run.
triggers = [
"pipelex/tools/log/console_fields.py",
"pipelex/tools/log/error_fields.py",
"pipelex/tools/typing/pydantic_utils.py",
]
review = [
"docs/tools/logging.md",
"docs/under-the-hood/log-sink-plugins.md",
]
verify_commands = []