Agent and Contributor Rules

Stack Identification

Before executing any task, audit the active dependency stack. Do not assume the presence of any library.

  1. Parse pyproject.toml ([project.dependencies] and [project.optional-dependencies]) and uv.lock to identify the exact versions in use.

  2. Use only libraries already declared in those files. Never introduce a conflicting or unlisted package without an explicit instruction to update dependencies.

  3. Apply the following decision matrix when selecting implementation patterns:

Concern

Source of truth

Current library

HTTP client

pyproject.toml

httpx

Data validation / models

pyproject.toml

pydantic v2

CLI framework

pyproject.toml

typer[all]

Retry logic

pyproject.toml

tenacity

HTTP mocking in tests

pyproject.toml (dev)

respx

Type checking

pyproject.toml (dev)

mypy

Linting

pyproject.toml (dev)

ruff

Formatting

pyproject.toml (dev)

ruff

Immutable Constraints

Credential Handling

  • Never log, print, write to disk, or transmit API keys, security keys, tokens, or authorization headers in plaintext under any circumstance.

  • Mask credential values in all log output and exception messages.

Testing Boundaries

Test location

Network access

Required mock library

tests/unit/

Forbidden — no live requests

respx for httpx, responses for requests

tests/integration/

Forbidden — use recorded fixtures

respx / responses

tests/live/

Permitted — real API calls

None (guarded by IMEDNET_RUN_E2E env var)

  • All new or modified code must include or update tests in tests/unit/.

  • Coverage must remain ≥ 90%.

  • Do not add tests/live/ calls to the default pytest run.

Commit Messages and Pull Requests

  • PR titles must follow Conventional Commits. Permitted prefixes: feat:, fix:, chore:, docs:, ci:, test:, refactor:, perf:, revert:. The Semantic PR Title CI check enforces this.

  • Merge to main via Squash and merge so the PR title becomes the commit message.

  • Changes that affect the public API, CLI interface, or environment variables must be noted in the PR description for Render deployment review.

Release Process

  • Do not manually edit package versions in packages/*/pyproject.toml. Versions are managed automatically by release-please.

  • Releases are fully automated. After merging a Release PR, release-please creates a package-specific Git tag and the Pipeline workflow publishes the tagged package to PyPI.