Project Bedrock

The atomic, testable engineering plan for building a governed, resilient agentic architecture. This roadmap translates the vision of the Architect's Blueprint into concrete, verifiable workstreams.

Workstream 1: Foundational Resilience & Stability

This workstream establishes a zero-tolerance policy for silent failures. The system must fail loudly and predictably when it cannot self-correct, implementing fail-fast mechanisms and a system-wide circuit breaker.

1.1: Fail-Fast Startup Validation

Prevent the system from running in a partially-functional state by validating critical components at startup.

Done When: An integration test proves the app terminates with `StartupValidationError` if a critical specialist fails to load.

1.2: Fail-Fast on Unknown Graph Routes

Eliminate silent, infinite-loop bugs by enforcing strict route validation within the graph orchestrator.

Done When: A test forcing a route to a non-existent node proves the orchestrator raises a `WorkflowError` immediately.

1.3: Standardize Self-Correction Signal

Create a decoupled mechanism for specialists to request a retry with clarification, increasing resilience to transient errors.

Done When: A test shows a mock specialist's `self_correction_request` correctly triggers a retry with the new prompt.

1.4: Define System Invariants

Establish the formal rules (State Integrity, Execution Constraints) that define a healthy system state.

Done When: Unit tests for each invariant function correctly identify violations in mock healthy and pathological states.

1.5: Implement InvariantMonitor Service

Implement the core logic for the system-wide circuit breaker and integrate it into the main execution loop.

Done When: An integration test asserts that monitor checks are called before and after every node execution.

1.6: Configure Circuit Breaker Actions

Define and implement the stabilization actions (e.g., HALT, ROUTE_TO_HUMAN) taken when an invariant is violated.

Done When: A test shows a triggered invariant violation correctly executes the configured stabilization action.
Workstream 2: The Explicit Control Plane

This workstream moves the system from implicit LLM inference for control flow to deterministic, structured communication. The Dossier, MCP, and Ranked Fallback patterns create a predictable control plane.

2.1-2.3: Implement Dossier Pattern

Establish the "Dossier" for explicit, state-mediated asynchronous communication. The orchestrator must prioritize, validate, and consume dossiers for deterministic routing.

Done When: Tests prove dossiers override other logic, are validated, and are consumed after one step.

2.4-2.6: Implement MCP

Define and implement the Message-Centric Protocol (MCP) for synchronous, direct tool invocation between specialists, and refactor a specialist to use it.

Done When: An integration test successfully invokes a specialist's function via the `McpClient`.

2.7-2.8: Purge State & Refactor Specialists

Perform a breaking change to remove all deprecated, specialist-specific fields from the global `GraphState` and update all specialists to use Dossier/MCP.

Done When: A comprehensive workflow test runs successfully using only the new communication patterns.

2.9-2.10: Implement Ranked Fallback Routing

Evolve the router's output from a single choice to a strategic, ranked plan, allowing the orchestrator to automatically try the next best option on failure.

Done When: A test with a failing specialist proves the orchestrator automatically executes the next specialist in the plan.
Workstream 3: The Hybrid Routing Engine

This workstream evolves the central router into a multi-stage decision engine. It combines procedural, declarative, and probabilistic strategies to make routing cheaper, faster, and more reliable.

3.1: Implement Reflexive Routing

Reduce latency and cost by handling simple, deterministic tasks with a procedural bypass, avoiding the LLM call entirely for trivial requests.

Done When: A test shows a configured input routes correctly and the router's LLM adapter was not called.

3.2-3.4: Implement Declarative Guardrails

Define a schema for routing policies (Guardrails) and implement a rule engine in the orchestrator to enforce them based on structured execution signals.

Done When: A test shows a specialist failure deterministically triggers a guardrail route without an LLM call.

3.5: Formalize Hybrid Routing Priority

Finalize the engine by ensuring a strict decision order: 1. Dossier, 2. Fallback, 3. Guardrail, 4. Reflex, 5. LLM. The LLM is the final escalation path.

Done When: Tests prove that a state matching a high-priority mechanism correctly bypasses all lower-priority ones.
Workstream 4: Professionalized Platform & Tooling

This workstream matures the project's infrastructure, observability, and deployment standards to a professional grade.

4.1: Unified Container Architecture

Establish a robust local development and deployment environment using Docker Compose with persistent volumes for state and artifacts.

Done When: `docker-compose down` and `up` correctly preserves memory state and generated artifacts.

4.2-4.3: Atomic Archival Tooling

Replace the monolithic Archiver specialist with a tool-based approach to create high-fidelity "Atomic Archival Packages" (.zip) for better observability.

Done When: A workflow test reaching the END state generates a valid archival package using the new tools.

4.4-4.6: AG-UI Event Stream

Implement middleware to translate internal LangGraph events into the standardized AG-UI format and expose them via a real-time API endpoint.

Done When: An end-to-end API test shows a client receiving a real-time stream of valid AG-UI events from a workflow.
Workstream 5: The Context Engineering Ecosystem

This workstream implements the meta-agentic subgraph that dynamically acquires, refines, and assembles the optimal context payload for "Solver" agents, using the communication patterns from Workstream 2.

5.1: Implement TriageArchitect (Planner)

Create a fast, tool-calling specialist that generates a structured "context acquisition plan" by consulting other specialists via MCP.

Done When: A unit test proves the specialist returns a valid `ContextPlan` object after a synchronous lookup.

5.2-5.3: Implement Researcher & Summarizer

Implement specialists for fetching external information (Researcher) and for semantic compression of large text artifacts (Summarizer).

Done When: Integration tests for each specialist prove they can be invoked and return standardized artifacts.

5.4-5.5: Implement Facilitator & Integrate

Create the orchestration logic (Facilitator) to execute the context plan, assemble the payload, and wire the entire ecosystem into the main graph.

Done When: An end-to-end test shows a user prompt correctly traverses the context subgraph before hitting the solver.