Repository navigation
feat(phase-0): implement contracts, common utilities, protocol stubs, fakes, tooling, and doctor - #3
Merged
Conversation
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
7 tasks done
Merged
7 tasks done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Build-Plan Step Implemented
Checkpoint Execution & Output
ADRs Relied On
Mock Registry Disclosures
Documentation Updates
Definition of Done
make checkgreen (ruff, mypy --strict, import-linter, pytest)# MOCKED:marker without a row in docs/MOCKS.md