contracts synchronizes subscribed fundamental contract Markdown files from the
central Victus documentation repository into this repository.
The sync destination is:
docs/contracts/fundamental/
The synchronized files are not authored directly in this repository. The local
script owns the source repository, source registry, and subscribed contract list.
Operators run the sync utility, validate the result, and review the generated
lock file before committing documentation changes.
The synchronization flow is intentionally file-based and deterministic:
ops/scripts/contracts.py declares the central source repository, sourcecontracts sync clones or updates the source repository in.cache/victus-contracts/.(contract_id, version) to a Markdown sourcedocs/contracts/fundamental/ whiledocs/contracts/ directory.docs/contracts/fundamental/contracts.lock.json records the source commit,Current local source configuration in ops/scripts/contracts.py points at:
SOURCE_REPO = "/home/carlos/victus/victus-docs"
SOURCE_REGISTRY = Path("docs/contracts/_registry/contracts.registry.yml")
SOURCE_CONTRACTS_ROOT = Path("docs/contracts")
The same utility also supports a remote Git source such as
git@github.com:carlos/victus-docs.git.
uv run contracts list
uv run contracts sync
uv run contracts validate
Optional path flags:
uv run contracts \
--contracts-dir docs/contracts/fundamental \
--cache-dir .cache/victus-contracts \
sync
Commands:
contracts list: prints subscribed contract ids and required versions.contracts sync: clones or updates the source repository, copies subscribeddocs/contracts/fundamental/, and writes the lock file.contracts validate: verifies subscriptions, registry entries, lock entries,Use this procedure when central contracts changed or when this repository needs
to subscribe to another fundamental contract.
Inspect current subscriptions:
uv run contracts list
Edit ops/scripts/contracts.py only when the source repository, registry
path, source contract root, or subscribed contracts must change.
Synchronize from the configured source:
uv run contracts sync
Validate the synchronized files and lock file:
uv run contracts validate
Review the diff before committing:
git diff -- docs/contracts/fundamental docs/300-CONTRACTS.md docs/operations/contracts-sync.md
Expected sync output lists each synchronized contract and destination path.
Expected validation output lists each locked contract and checksum.
There is no local subscription YAML file. The operational configuration lives in
ops/scripts/contracts.py:
SUBSCRIPTIONS = (
("victus.scientific.paper", "v1"),
("victus.scientific.structured_block", "v1"),
("victus.scientific.paper_classification", "v1"),
("victus.scientific.experiment_map", "v1"),
("victus.scientific.canonical_evidence", "v1"),
("victus.orchestration.pipeline_run", "v1"),
("victus.orchestration.pipeline_event", "v1"),
("victus.storage.layout", "v1"),
("victus.storage.artifact_manifest", "v1"),
("victus.process.paper_classification", "v1"),
)
Operational notes:
SOURCE_REPO is passed to git clone for first use and updated withgit fetch --depth 1 origin plus git pull --ff-only on later runs.SOURCE_REGISTRY must be a relative path inside the source checkout.SOURCE_CONTRACTS_ROOT defines the central path prefix removed before writingdocs/contracts/fundamental/.contract_id values fail validation.The source registry may be a top-level list or an object containing
contracts.
contracts:
- contract_id: victus.scientific.paper
version: v1
path: docs/contracts/scientific/paper.md
- contract_id: victus.scientific.canonical_evidence
version: v1
path: docs/contracts/scientific/canonical-evidence.md
Required registry fields:
contract_idversionpathPath:
docs/contracts/fundamental/contracts.lock.json
Example:
{
"synced_at": "2026-06-10T12:00:00+00:00",
"source_commit": "4f34f3a9a86b7a1e8a24d604cb2d9c3d1d5d3a11",
"contracts": [
{
"contract_id": "victus.scientific.paper",
"version": "v1",
"source_path": "docs/contracts/scientific/paper.md",
"destination_path": "docs/contracts/fundamental/scientific/paper.md",
"checksum": "sha256:8f5b2f4b1e3a9e9d0c0c5f1e9c7a2d8c4b7f1d0a2e3c4b5a6d7e8f9a0b1c2d3e"
}
]
}
The lock file is generated by contracts sync. Operators should not hand-edit
it except to resolve a failed merge with the same content that a clean sync would
produce.
Lock fields:
synced_at: UTC sync timestamp.source_commit: central source checkout commit used for the sync.contracts[].source_path: source Markdown path from the central registry.contracts[].destination_path: local synchronized path.contracts[].checksum: SHA-256 checksum of the local copied file.Validation repeats steps 1-3, then verifies:
docs/contracts/fundamental/;Run validation after every sync and before preparing a commit that changes
fundamental contracts.
uv run contracts sync..cache/victus-contracts/, then rerun sync.ops/scripts/contracts.py or add the missingThe sync operation is idempotent for the same source commit and subscriptions.
Rerunning contracts sync overwrites synchronized Markdown files under
docs/contracts/fundamental/ and rewrites contracts.lock.json.
docs/contracts/fundamental/.docs/contracts/.contract_id values fail.(contract_id, version) source registry entries fail.This document owns the procedure for synchronizing and validating fundamental
contracts in this repository.
It does not define the contract content itself. Fundamental contract semantics
live in the central documentation repository and are copied locally under
docs/contracts/fundamental/. Repository-local implementation contracts live
under docs/contracts/local/.