Skip to content

feat(phase-0): implement contracts, common utilities, protocol stubs, fakes, tooling, and doctor - #3

Merged
Harikeshav-R merged 13 commits into
mainfrom
feat/phase-0-foundations-and-contracts
Sep 10, 2026
Merged

Harikeshav-R merged 13 commits into
mainfrom
feat/phase-0-foundations-and-contracts

Conversation

@Harikeshav-R

Copy link
Copy Markdown
Owner

Build-Plan Step Implemented

  • Step: Phase 0 - Steps 0.3, 0.3a, 0.4, 0.5, 0.6, 0.7, 0.8

Checkpoint Execution & Output

make check:
uv run ruff format --check . -> 73 files already formatted
uv run ruff check . -> All checks passed!
uv run mypy --strict src tests -> Success: no issues found in 73 source files
uv run lint-imports -> Contracts: 5 kept, 0 broken.
uv run pytest --cov=understudy --cov-branch --cov-fail-under=100 -> 69 passed, 100.00% coverage.

uv run python -c "from understudy.orchestrator.api import Orchestrator; print(\x27protocols importable\x27)"
protocols importable

uv run python -c "from understudy.orchestrator.fakes import create_fake_deps; deps = create_fake_deps(); print(\x27fake deps constructible:\x27, deps.__class__.__name__)"
fake deps constructible: Deps

checkpoint: unverified (ust doctor exited 1 locally because Docker memory allocated is 7.7 GB < 12 GB per ADR-003, and live API secrets are not set in the local development environment)

ADRs Relied On

  • ADR-003: 18 GB RAM is a first-class design constraint with a written budget (Docker >= 12 GB checked by doctor)
  • ADR-004: Python everywhere, 3.12 (enforced by doctor and tooling)
  • ADR-005: LangGraph is the orchestration layer (deps injection seam in orchestrator/api.py)
  • ADR-006: Component contracts are Pydantic models in a dependency-free package
  • ADR-007: Every component ships a real implementation and a fake, behind a Protocol
  • ADR-028: Production actuation is real, gated, and rate-limited (FakeActuator enforces PASS verdict)

Mock Registry Disclosures

  • None

Documentation Updates

  • None required (all code matches docs/02-architecture.md §2.3 and §2.4, and CHECKLIST.md was updated with completed steps).

Definition of Done

  • Implementation complete for the named build-plan step
  • Unit tests written; 100% line and branch coverage of the added lines
  • make check green (ruff, mypy --strict, import-linter, pytest)
  • Checkpoint command run and output matches, OR marked unverified with a reason
  • Docs updated where this change made them untrue (or "none required", with why)
  • No new # MOCKED: marker without a row in docs/MOCKS.md
  • Conventional commit(s), conventional branch, PR opened, never pushed to main

Harikeshav-R and others added 13 commits September 9, 2026 19:23
Establish the core contract boundary defined in architecture §2.4. All
models and enums are immutable and frozen under Pydantic v2 to guarantee
cross-stream isolation without runtime dependencies. Includes serialization
round-trip unit tests covering every model and property.

Implements build-plan step 0.3 and step 0.3a.
…etry

Provide shared foundational utilities for Understudy: layered YAML and
environment configuration loader, structured JSON logging bound with
incident_id, Clock protocol with deterministic FrozenClock, Crockford
Base32 ULID identifier generators, domain error hierarchy, and tenacity
retry decorators.

Implements build-plan step 0.4.
…onents

Declare typing.Protocol stubs for every component in architecture §2.3:
RunStore, PlaybookStore, EvalStore, AlertSource, ObservabilityAdapter,
DeployHistory, DependencyGraph, BlastRadiusCalculator, PlaybookLibrary,
Planner, FleetController, MirrorRegistry, Tournament, SafetyKernel,
Actuator, Notifier, ShadowLoop, Orchestrator, and EvalHarness, along with
Deps container and orchestrator stubs.

Implements build-plan step 0.5.
Implement deterministic in-memory fakes conforming to each component
protocol under src/understudy/<pkg>/fakes.py, including create_fake_deps()
to assemble a complete Deps container for offline and unit testing without
external clusters or databases. Includes unit tests with 100% line and branch
coverage.

Implements build-plan step 0.6.
…hecks

Encode architectural boundaries in .importlinter ensuring contracts,
common, store, fleet, actuator, and orchestrator boundaries are strictly
enforced. Update .pre-commit-config.yaml with mypy and conventional commit
checks, initialize secrets baseline, and wire GitHub Actions workflow
to make check.

Implements build-plan step 0.7.
Implement ust doctor verifying Python 3.12, CLI tools (uv, kubectl, k3d),
Docker Desktop memory allocation >= 12 GB per ADR-003, and resolution of
required API secrets. Update CHECKLIST.md with Phase 0 step completions.

Implements build-plan step 0.8.
Explicitly specify in AGENTS.md §3, §4, and §9 that agents must never
merge pull requests or enable auto-merge, ensuring that code review and
PR merging remain exclusively human actions.
Document ADR-034 establishing OpenRouter as the model-agnostic LLM
and embeddings provider via its OpenAI-compatible endpoint. Update
architecture secrets, build plan agent dependency specifications, and
reproduction guides to reflect OpenRouter keys and model-agnostic
configuration.

Implements build-plan step 0.1.
Replace Anthropic SDK dependencies with OpenAI-compatible client libraries
(openai, langchain-openai) to communicate with OpenRouter. Add model-agnostic
configuration settings (llm_model, embedding_model, openrouter_base_url) and
update doctor preflight to check OPENROUTER_API_KEY and PAGERDUTY_ROUTING_KEY.
Provide global test fixture in tests/conftest.py to isolate unit tests from local
developer .env files.

Implements build-plan step 0.1.
Update Checkpoint 0 in CHECKLIST.md to mark ust doctor and PR CI
checks as verified following successful preflight run and green GitHub
Actions test runs on PR #3.

Implements build-plan step 0.8.
…ew findings

Replace direct datetime.now calls across all component fakes with explicit Clock
injection and incorporate seeds to uphold determinism guarantees required by
AGENTS.md §5.7 and build-plan step 0.6. Refactor layered configuration loading to
deduplicate YAML parsing, use table-driven environment overrides, and support
macOS Keychain secret lookup via keyring fallback. Change default retry exceptions
to UnderstudyError to avoid catching bare Exception, update doctor memory preflight
to decimal 12 GB, eliminate type-ignore in FakePlaybookStore with TypedDict, add
AST tests enforcing sibling import boundaries, and reset unverified PR CI status.

Implements build-plan step 0.6 and Phase 0 code review remediation.
…onfig, mocks, and fakes

Fixes 10 issues from a background code review: broadens keyring exception
handling so config loading degrades gracefully, hardens check_mocks.py's
path exclusion and module-matching logic, restores lowercase ULID output
for K8s naming compatibility, isolates test env vars from the real shell
environment, fixes FakeOrchestrator's clock divergence from its deps,
falls back to Pydantic field types for nested env-var coercion when no
YAML default exists, restores RunStore.get_active_runs for the K5 kernel
invariant's documented fact source, documents retry()'s narrowed default,
and dedupes the Clock DI pattern across fakes.py modules via a shared
resolve_clock() helper.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PxxvJnsSDciEFbTJzULnVr
@Harikeshav-R
Harikeshav-R merged commit 2b6f77a into main Sep 10, 2026
2 checks passed
@Harikeshav-R
Harikeshav-R deleted the feat/phase-0-foundations-and-contracts branch September 10, 2026 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant