Roadmap

yoagent-state starts with an event-sourced graph runtime: append-only events, replayed graph projection, goal-first lineage, patch lifecycle, artifacts, policies, behaviors, forks, examples, and mdBook docs.

This roadmap lists the likely next steps without turning the project into a workflow engine, graph database, Git replacement, or universal agent framework.

Current Implementation

Implemented:

• Core ID, actor, event, artifact, patch, precondition, and expected-effect types.
• MemoryEventStore and JsonlEventStore.
• Append-only event recording and replay into an in-memory graph.
• State operations for nodes, relations, stale markers, tombstones, and artifacts.
• Goal, task, run, observation, failure, hypothesis, patch, eval, decision, project snapshot, model call, tool call, frame, fork, behavior, policy, pack, and view IDs.
• Goal/task helpers, failure observation, hypothesis records, patch proposal, patch status changes, eval records, decision records, and lineage queries.
• Runtime layer for typed packs, policy gates, behavior subscriptions, replay, fork, and diff.
• Small yoagent sink adapter for run/model/tool lifecycle events.
• Coarse project observer helpers for changed files and diff artifacts.
• CLI for init, events, graph, node, lineage, goal create/list/show/status, patch list/show/promote, replay, and fork create.
• Examples and regression tests for the main state flows.
• mdBook user guide.

The current core graph shape is:

goal -> task -> run -> observation -> failure -> hypothesis -> patch -> artifact -> eval -> decision -> promotion

flowchart LR
  goal["goal"]
  task["task"]
  run["run"]
  observation["observation"]
  failure["failure"]
  hypothesis["hypothesis"]
  patch["patch"]
  artifact["artifact"]
  eval["eval"]
  decision["decision"]
  promoted["promoted status"]

  task -- serves --> goal
  run -- produces --> observation
  observation -- observes --> failure
  hypothesis -- explains --> failure
  patch -- addresses --> failure
  patch -- advances --> goal
  patch -- references --> artifact
  patch -- validated_by --> eval
  patch -- approved_by --> decision
  decision --> promoted

This is a causal spine. It does not require every flow to create every node.

Phase 1: Runtime Hardening

Goal: make the current crate more reliable for early users.

• Add crate-level API examples as Rust doc tests.
• Add tests for tombstones, stale nodes, artifact attachment, relation deletion, and error cases.
• Add CLI integration tests using temporary JSONL event logs.
• Add schema compatibility tests for serialized event and patch JSON.
• Add stricter validation for patch status transitions.
• Add markdown lineage report tests so output remains stable.
• Improve error messages for malformed JSONL and missing nodes.

Success criteria:

• Public examples compile as doc tests.
• CLI behavior is covered by regression tests for goal, patch, replay, and fork commands.
• Event JSON compatibility is protected by fixtures.

Phase 2: Persistence and Replay

Goal: make local state durable and inspectable beyond simple demos.

• Make JSONL append safer for concurrent writers.
• Add compaction or snapshot support for large event logs.
• Add scan_after coverage for missing IDs and resumed replay.
• Add optional SQLite storage after JSONL behavior is proven.
• Add import/export commands for portable state bundles.

Success criteria:

• Restart/replay is reliable with larger logs.
• Users can choose JSONL for simplicity or SQLite for local scale.

Phase 3: Better Query and Reports

Goal: answer practical “why does this exist?” questions directly.

• Add focused query helpers:
  • patches for failure
  • evals for patch
  • decisions for patch
  • artifacts for node
  • files modified by patch
  • stale assumptions related to patch
• Expand markdown lineage reports with grouped sections:
  • status
  • addresses
  • evidence
  • evals
  • modified files
  • decisions
  • promotion references
• Add JSON and markdown output options consistently to CLI commands.

Success criteria:

• One command can show why a patch exists, what validated it, what files changed, and whether it was promoted.

Phase 4: Project Observer v0+

Goal: connect semantic patches to concrete project diffs without becoming a compiler.

• Add git command helpers for changed files, base commit, and diff artifact creation.
• Hash important artifacts such as diffs, logs, and eval outputs.
• Detect common project changes:
  • tests added or changed
  • docs changed
  • dependency manifest changed
  • source files changed
• Add base commit precondition helpers.
• Mark patches stale or conflicted when the project base changes.

Success criteria:

• A patch can automatically reference changed files, base commit, diff artifact, and basic project facts.

Phase 5: yoagent Integration

Goal: let yoagent emit durable state without becoming state-heavy.

• Wire the adapter into real yoagent run hooks.
• Record model/tool causation and correlation IDs.
• Attach selected tool outputs as artifacts.
• Add examples that use the actual yoagent crate once its integration point is stable.
• Add tests for failed tool calls becoming failure observations.

Success criteria:

• yoagent can run normally with optional state recording enabled.

Phase 6: yoyo evolve Demo

Goal: prove the growth loop end to end.

• Create a demo command that:
  • observes a failure
  • proposes a patch
  • records a diff artifact
  • runs an eval command
  • records eval output
  • approves or rejects the patch
  • prints a lineage report
• Use temporary branches or worktrees for patch evaluation.
• Keep promotion explicit and evidence-backed.

Success criteria:

• One demo shows goal -> task -> failure -> patch -> diff artifact -> eval -> decision -> promotion with a readable lineage report.

Phase 7: Policy and Safety Gates

Goal: make risky mutation explicit.

• Add policy checks for:
  • prompt mutation
  • tool configuration changes
  • memory/state mutation
  • project patch promotion
• Expand policy decisions as first-class decision nodes across more runtime actions.
• Require evidence before promotion.
• Add stale/conflicted status helpers for unsafe bases.

Success criteria:

• The library makes self-modification visible, reviewable, and auditable.

Later, Only If Needed

Potential extensions:

• More behavior subscription patterns beyond “failure observed -> create task”.
• Richer fork merge and promotion workflows.
• Richer project observers for Rust symbols, Cargo dependencies, and test surfaces.
• Web or TUI inspection UI.
• Remote artifact storage.
• Multi-agent views over the same state log.

These should wait until real yoyo evolve runs show that the added complexity is worth it.

Non-Goals to Preserve

Do not turn yoagent-state into:

• a replacement for Git
• a workflow engine
• a graph database platform
• a compiler or AST database
• a universal memory system
• a hidden self-modification mechanism

The guiding rule remains: simple but effective.