Roadmap

Preamble — "live build list"

Everything between today and a full-fledged general-purpose agent runtime; status is measured, not aspirational. Legend: [x] done, [~] partial, [ ] not started, B blocks other work, ! known-false claim shipping today. Overall ~70% of the list (72 of 103 enumerated items), re-derived 2026-07-28 by executing every claim against the tree rather than reading the commit log — the percentage is the fraction of enumerated items verified done, this project's own definition of scope and not the industry's. At that point: pytest → 1,381 passed, 10 deselected; ruff check . clean; the wheel imports all 94 submodules in a clean virtualenv. Four subsystems were once built, tested and reachable by nothing (planner/, policy/, the CLI's memory store, cost on trace events); all four are closed and one seam is left — server/ still ships its own in-process session runtime instead of the durable session/ one (§12.3).

Next five things

In order: (1) Put the HTTP API on the real session layer (§12.3) — the last seam; two session layers, one seam. (2) Let admission constrain arguments (§5.6) — ! the gap most likely to be over-read; a rule reaches a node's kind and never its args. (3) Route the tool plane through the document (§7.5 remainder) — nothing calls permission_policy(), so grapharc agent is still governed by Python objects rather than the TOML file. (4) ~~Publish to PyPI~~ (§11.1) — done, 0.1.0 is live; next is 0.1.1 to correct the __version__ the wheel carries, built only from a clean tree via the tag-driven release.yml rather than a local uv build. (5) ~~Decide the version~~ — decided: 0.1.0; a 1.0 would imply API stability that several days-old subsystems do not have.

0. Correctness debt — ship-blockers, section clear

Every item verified by running code; all shipped.

• [x] 0.1 — ctypes escape closed, plus sqlite3.connect, _posixsubprocess.fork_exec, and compiled-extension imports from outside the runtime paths.
• [x] 0.2 — Child environment scrubbed to an allowlist.
• [x] 0.1b — Runtime paths are read-only; a sandboxed tool writing evil.pth raises SandboxViolation while stdlib reads still succeed.
• [x] 0.3 — max_seconds interrupts a running node (SIGALRM on the main thread, async-exception injection elsewhere) and re-arms.
• [x] 0.4 — Tokens charge automatically via a usage callback, deduplicated by call identity; max_tokens enforced at on_llm_end.
• [x] 0.5 — Types validated at write time (annotation constraints bite; a model's own @field_validator does not run at write time).
• [x] 0.6 — README claims corrected, each disproof re-run.
• [x] 0.7 — Neo4j fiction removed; a real ClaimStore protocol exists.
• [x] 0.8 — pytest defaults fixed: addopts carries -m 'not live'.
• [x] 0.9 — LICENSE copyright and README clone URL corrected.
• [x] 0.10 — Gateway tempfile leak fixed via an ExitStack-managed TemporaryDirectory with ignore_cleanup_errors=True.

1. Graph kernel — [~] ~85%

No longer amputates LangGraph; async, Command returns and state access all came through, which unblocked the HTTP API and the session layer.

• [x] Typed state, per-node declared writes, deep-copy isolation
• [x] Budgets (iterations/tokens/seconds/concurrency), convergence guards, DAG mode, cycle detection
• [x] JSONL traces, checkpoint resume, fail-closed run context
• [x] Bounded fan-out with worker isolation and dedup
• [x] 1.1 — Async ainvoke/astream/astream_events; sync entry points refuse async graphs with AsyncNodeError; v3 refused.
• [x] 1.2 — Command returns accepted (update goes through the write allowlist, goto validated at the node boundary); a Command as input stays unsupported deliberately.
• [x] 1.3 — get_state / update_state / get_state_history passthrough plus a* twins; update_state rejects unknown fields and type-checks.
• [x] 1.7 — TraceRecorder.thread_summary is incremental: O(events) over a thread's life rather than O(events²).
• [~] 1.5 — interrupt() half-works: suspend is real, no supported resume; still writes a spurious phase="error" line carrying the GraphInterrupt.
• [ ] 1.4 — Passthrough retry_policy, cache_policy, durability, subgraphs.
• [ ] 1.6 — Offer a decorator form so discipline composes with LangGraph instead of replacing it.
• [ ] 1.8 — Make deep-copy opt-out-able for large states (currently unconditional).

2. Model gateway — [~] ~80%

• [x] Claude Code CLI adapter (tools disabled, argv array, stdin prompt); correct cache-token accounting
• [x] 2.1 — bind_tools works on OpenRouter; still NotImplementedError on Claude-CLI (inherent to claude -p).
• [x] 2.2 — with_structured_output works on OpenRouter.
• [x] 2.3 — _stream and _agenerate both work on OpenRouter.
• [x] 2.5 — RetryPolicy: 3 attempts, 0.5s initial, ×2, capped 20s, 25% shrinking jitter, explicit transient/deterministic split; streaming not retried.
• [x] 2.6 — Routing rules: provider order/sort/max_price/require_parameters plus model-level fallback_models.
• [x] 2.7 — Enforced cost ceilings via SpendMeter (ensure_headroom before, raise after charging); unpriced calls land in unpriced_calls.
• [x] 2.9 — Backend registry: claude-cli, openrouter, openai, ollama, mock; openai is both a backend and an OpenRouter author slug and the backend wins.
• [~] 2.4 — Provider adapters: OpenRouter, Claude CLI, OpenAI API, local Ollama, mock; the three OpenAI-wire backends share one base class. Direct Anthropic API and vLLM pending; the api extra exists with nothing importing anthropic.
• [ ] 2.8 — Prompt caching support and per-run model pinning.

3. Tool plane — [~] ~55%

• [x] Registry, deny→ask→allow permissions, hooks, approval gates; audit-hook executor (path confinement, network gating, spawn refusal, SIGKILL escalation)
• [x] 3.1 — Wired to an agent: AgentNode drives registry, permissions and executor; grapharc agent <task> drives the core toolset; examples/agent_fixit.py is a shipped graph that calls tools.
• [x] 3.2 — Container executor at grapharc/harness/container.py; live-runtime tests skip when no runtime or image is present and never pull one (exercised against Docker with python:3.12-slim).
• [x] 3.3 — Core tools: read_file, write_file, edit_file, list_dir, glob, grep, run_command.
• [ ] 3.4 — Browser tool and HTTP/network tool.
• [ ] 3.5 — MCP client (the mcp extra exists with nothing importing it).
• [ ] 3.6 — Progressive disclosure / tool search for large tool sets (ToolRegistry.visible() filters by permission, a different thing).
• [ ] 3.7 — Idempotency keys for side-effecting tools.
• [ ] 3.8 — Large-output offloading (ToolLimits truncates at 20,000 chars; nothing is offloaded).

4. Agent node — [~] ~60%

• [x] 4.1 — AgentNode built: observe → model → tool request → permission check → sandboxed execute → repeat, budgeted and traced. A denied tool is fed back to the model rather than killing the run; malformed tool JSON is reported back; stall detection keys on the tool result; only target_met fills the answer field, otherwise the last utterance stays in partial_output.
• [ ] 4.2 — Context management (compaction, just-in-time retrieval).
• [ ] 4.3 — Subagent spawning with context isolation and summary-only return.
• [ ] 4.4 — Skills / instruction packs loaded on demand.
• [ ] 4.5 — Per-node model and effort tiering.

5. Planner & admission — [~] ~85% — the crux, and it closed

• [x] 5.1 — Planner node that proposes rather than acts; Subgraph/ProposedNode forbid extra fields so a body= key is a ValidationError.
• [x] B 5.2 — Admission checker: five checks (registry, policy, budget, depth, acyclicity), all run on every proposal; nothing executes during a check; every decision keys on kind, never name; worst-case cost summed from the registry.
• [x] 5.3 — Rejections are first-class traced phase="admission" events carrying status, fingerprint, checks run and failed codes.
• [x] 5.4 — Replanning with loop protection: AdmissionResult.feedback() becomes the planner's next input; nine stop reasons including no_progress, max_rounds, admission_refused, planning_failed; the loop cannot fall out of the bottom.
• [x] 5.4b — Materialisation binds to the authorisation by fingerprint (NotAdmitted); Command(goto=…) confined to the admitted edge set with UnadmittedTransition.
• [ ] 5.5 — Decomposition strategies (map-reduce, specialist fan-out) as reusable planner presets.
• [ ] ! 5.6 — Admission cannot constrain arguments; forward_args=True hands the raw dict to a factory unchecked. Admission authorises the verb, not the object.

6. Session runtime — [~] ~85%

• [x] 6.1 — Long-lived sessions with a status lifecycle in a SessionStore.
• [x] 6.2 — Resume across process restart, verified across two interpreters; append-only log shows each node exactly once; resuming process must register the graph or gets UnknownGraphError.
• [x] 6.3 — Interrupt and steering at superstep boundaries.
• [x] 6.4 — Event queue for multi-turn input, durable in the store.
• [x] 6.5 — Human approval as a suspending graph node via LangGraph interrupt_before; every gated node on a superstep boundary held separately with its own request id — a signature on send_email is not a signature on delete_records.
• [x] 6.6 — Concurrent sessions with isolation, each on its own thread.
• [ ] 6.7 — Async turns (run() is synchronous and occupies its caller until the session stops).
• [ ] 6.8 — A real runner lease; nothing reclaims a session whose runner died holding it. That is a claim, not a lease.

7. Policy engine — [~] ~75% built, 0% wired

• [x] 7.1 — Declarative TOML policy over nodes, edges, tools and spend; tiered rather than positional evaluation (every deny before every ask before every allow); example at grapharc/policy/example.toml.
• [x] 7.2 — Approval routing: ask rules carry a required approver_role; engine.approval_router(handlers, tenant=…) and engine.permission_policy(tenant=…).
• [x] 7.3 — Policy versioning and decision audit in JSONL naming resource, subject, tenant, effect, rule id, reason, policy version and document digest.
• [x] 7.4 — Multi-tenant scoping; a rule scoped to an unknown tenant is a load error and a request naming one is a recorded denial.
• [x] 7.5 — The document reaches the gate via edge_policy(tenant=…), with grapharc plan --policy as a shipped caller.

8. Memory & artifacts — [~] ~85%

• [x] Claims with provenance, supersession instead of overwrite, Unicode-safe entity normalization
• [x] 8.1 — SQLiteMemoryStore verified durable across genuinely separate processes.
• [x] 8.2 — SQLiteArtifactStore on the same file: append-only with versions, mandatory provenance, content-addressed blobs written before the referencing row; name is metadata and never used to build a path.
• [x] 8.3 — Real retrieval: BM25F over subject+predicate+object, optional vector channel with a similarity floor, graph traversal with per-hop score decay; every result list sorted by a total order so both backends rank identically.
• [x] 8.4 — Automatic contradiction detection (detect_contradictions, add_and_detect) — structural, not semantic; reports and never resolves.
• [x] 8.5 — Token-budgeted context rendering: render_context takes max_tokens, max_dead_ends and a count_tokens callable.
• [x] 8.7 — grapharc run --memory PATH gives stage6 and capstone the SQLiteMemoryStore; in-process remains the default.
• [ ] 8.6 — Per-tenant/user memory scoping.

9. Triggers & surfaces — [~] ~55%

• [x] CLI (run / trace / metrics / viz)
• [x] 9.1 — HTTP API: seven FastAPI routes (create, list, get, post event, SSE stream, NDJSON trace, healthz), verified end to end including 404 on unknown session/graph and 422 on input failing the state schema; behind the server extra.
• [x] 9.2 — Real CLI: ten commands — run / plan / agent / serve / models / replay / diff / trace / metrics / viz — every one with --json; exit codes 0/1/2 are part of the interface.
• [x] 9.6 — Streaming output to clients via SSE with a last-event-id cursor so a reconnect skips what it already saw.
• [ ] 9.3 — Cron schedules; 9.4 — webhook triggers.
• [ ] 9.5 — Chat channels (Slack / Discord).

10. Operations — [~] ~60%

• [x] JSONL traces, metrics summaries, Mermaid path rendering
• [x] 10.1 — Replay a run from its trace: a reconstruction, not a re-execution; diff_runs / diff_trace align two runs and report where they diverged.
• [x] 10.3 — OpenTelemetry export, one root span per run and one child per node execution, dependency confined behind a Protocol; verified this pass against opentelemetry-sdk 1.44.0 with spans reaching an InMemorySpanExporter.
• [~] 10.4 — Cost attribution per run, thread (session) and node; price recorded not guessed, recorded_cost_usd and estimated_cost_usd never mix. One gap left: no tenant on a trace event.
• [ ] 10.2 — Rollback and versioned graph/prompt configs.
• [ ] 10.5 — Alerting on budget, failure, and verifier-drift.

11. Product & distribution — [~] ~35%

• [x] Builds a clean wheel; 1,534 tests; CI; ruff clean; a bare wheel install imports most of the 103 submodules (gateway.openrouter and the whole server package need their extras).
• [x] 11.6 — Classifiers, [project.urls], contribution guide; every URL names a file that exists and the all extra is self-referential.
• [x] 11.7 — The source is on the public remote; git clone … && uv sync --group dev works. This was the single most consequential false claim in the tree for most of the project's life, because it was the first one a reader hit.
• [x] 11.1 — Publish to PyPI: 0.1.0 is live, verified in a clean virtualenv through to grapharc demo stage0.
• [~] 11.3 — Live-model examples behind the live marker: 10 tests, deselected by default; CI wiring still pending (needs a key in secrets).
• [~] 11.2 — Docs site: a cookbook is landing under docs/cookbook/; no published site.
• [ ] 11.2 — Ship 0.1.1 to correct the __version__; build only from a clean tree (git status empty, then uv build).
• [ ] 11.4 — Benchmarks, including published losses.
• [ ] 11.5 — External security review (the audit-hook sandbox is defense in depth; §3.2's container executor is the boundary to review).

12. Seams — [~] ~80%

Each item is two working subsystems that do not know about each other; none is research, and all are worth more than another feature. Four of the five are closed.

• [x] 12.1 — A surface for the governed loop: grapharc plan <goal> drives propose → admit → materialise → execute → replan and prints every round, its admission status and rejection codes; --model SPEC, --registry module:attr (plus STATE_SCHEMA and WRITES); tests/test_cli.py pins rounds, stop reason and exit codes.
• [x] 12.2 — PolicyDocument → EdgePolicy via PolicyEngine.edge_policy(tenant=…); pinned to check_edge across an edge × tenant matrix, an undeclared tenant compiling to a policy that permits nothing; grapharc plan --policy PATH --tenant NAME is the caller, and with a *->deploy deny rule round 1 is refused while removing the rule admits it.
• [x] 12.4 — A durable store for the shipped graphs (grapharc run --memory PATH), proved across a real process boundary.
• [x] 12.5 — cost_usd onto trace events (see §10.4).
• [ ] 12.3 — The HTTP API on the real session layer: create_app(runtime=…) already takes any SessionRuntime; missing is the implementation backed by grapharc.session, which would give durable sessions, cross-process resume, and approval events that are delivered rather than merely recorded.

Milestones

Five milestone rows, each with scope, a gate stated as a real task against a real model, and a measured status. V0 (§0 + §2.1 + §4.1 — an agent edits a file and runs tests, permission-gated and budgeted) passed. V1 (§5 + §1.1–1.2 — "Refactor this repo and run tests" plans its own fan-out; an over-budget plan is rejected with a recorded reason) mechanism done, gate not run. V2 (§6 + §8.1 — a session survives restart; a human approves a destructive action mid-run) mechanism done, gate not run, verified across two processes with a scripted model. V3 (§7 + §9 — incident response runs from a webhook, remediation gated on approval) blocked on §12.2 and §9.4. V4 (§10 + §11 — replay any production run; a stranger pip installs it) replay works; nobody can install it (dated against §11.7).