Agent readiness

This repository follows the reusable readiness pattern proven in the sibling telemetry repository: an unfamiliar agent should be able to set up, navigate, change, verify, and hand off work without guessing. AGENTS.md is the entry point; this document records the broader evidence and remaining external activation.

Reproducible and executable

• .python-version, uv.lock, pinned CI actions, a pinned telemetry commit, and locked installs bind the authoritative environment.
• make setup is the non-interactive bootstrap; make doctor diagnoses prerequisites, lock drift, the sibling dependency, and the environment.
• Unit and contract state is per test. Synthetic data and simulation scenarios have explicit seeds, bounds, and logical time.
• CI installs on a clean self-hosted Apple Silicon macOS job and verifies the built wheel outside the source tree.

Reliable feedback

testing.md defines a focused-to-complete command ladder. CI retains JUnit, branch coverage, package digests, runner/dependency identity, and installed-wheel evidence. Contribution and pull-request checklists require regression evidence and explicit review of weakened tests, skips, thresholds, and acceptance criteria.

Discoverable knowledge

index.md routes by question. CONTEXT.md, the approved specification, implementation reference, architecture summary, testing guide, troubleshooting guide, operational runbooks, ADRs, and contract tests each have a declared role. .scratch/ is private planning history and is not an authority.

Executable boundaries

• Pydantic models, dataclasses, enums, strict configuration loaders, and migrations define public and durable contracts.
• make architecture-check enforces reusable-package and telemetry import boundaries.
• make docs-check rejects broken local links and missing command-surface targets.
• py.typed markers and strict mypy make both shipped packages navigable.
• Tests control clocks, databases, HTTP clients, external recommendation calls, and simulation traffic at explicit seams.

Measurement

Use agent-runs/README.md for three representative fresh-environment tasks: a public API/configuration change, a pipeline or storage defect, and a migration or simulation change. Record completion, regressions, elapsed time, cost when available, human intervention, and one failure class. Until all three reviewed records exist, this repository claims harness readiness, not measured autonomous performance.

Readiness audit

Requirement	Status	Evidence or disposition
Pinned toolchain and dependencies	Implemented	.python-version, uv.lock, pinned actions and telemetry commit
One setup and diagnostic command	Implemented	make setup, make doctor
Focused, static, layered, and smoke checks	Implemented	Makefile and docs/testing.md
Fresh installed-artifact verification	Implemented	make smoke and package CI job
Stable agent entry point and domain context	Implemented	AGENTS.md, CONTEXT.md, docs index
Architecture and documentation contracts	Implemented	validator scripts and CI
Test seams and deterministic synthetic state	Implemented	unit/contract/integration suites and simulation scenarios
Secret and production-data exclusions	Implemented	security policy, agent invariants, ignore files
Self-hosted macOS ARM64 CI	Implemented	explicit runner labels and arm64 Python setup
Cross-repository CI access	External activation	TELEMETRY_REPOSITORY_TOKEN must be configured
Required merge checks	External activation	enable stable CI job names in branch protection
Representative agent-task baseline	Measurement pending	docs/agent-runs/ protocol
Specialist repository skills or retrieval index	Conditional	add only after measured repeated failures justify upkeep