grove

<p align="center"> <picture> <source type="image/webp" srcset=".github/assets/hero.webp" /> <img src=".github/assets/hero.png" alt="Grove" /> </picture> </p> <p align="center"> <a href="https://notebook.google.com/notebook/434f3efc-c199-4b7e-ac61-92fbd85d655e"><img src="https://img.shields.io/badge/Notebook-q/a-8A2BE2?style=for-the-badge" alt="Notebook" /></a> <a href="docs/install.md#verify-before-you-run"><img src="https://img.shields.io/badge/signing-RSA--PSS-8A2BE2?style=for-the-badge" alt="Release signing" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/open%20source-AGPL_3.0-8A2BE2?style=for-the-badge" alt="AGPL 3.0 license" /></a> <a href="https://github.com/alxshelepenok/grove/actions/workflows/rust-tests.yml"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Falxshelepenok%2Fgrove%2Fbadges%2F.github%2Fbadges%2Ftests.json&style=for-the-badge" alt="Tests" /></a> <a href="packages/grove/conformance"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Falxshelepenok%2Fgrove%2Fbadges%2F.github%2Fbadges%2Fconformance.json&style=for-the-badge" alt="Conformance" /></a> </p> <h3 align="center"> Code grows. Context windows don't. Plant a <i>Grove</i> 🌳 </h3> <p align="center"><i><b>G</b>raph-driven <b>R</b>easoning <b>O</b>ver <b>V</b>erified <b>E</b>vidence. A formal workflow protocol designed to keep deep, long-running projects coherent across sessions, agents, and months.</i></p> Long-running agent work fails in a predictable way: decisions and assumptions drift out of view as sessions grow, agents report work done that is not done, and after a few months the codebase no longer matches what anyone believes about it, so nobody can say why a given line exists. Grove fits reasoning-heavy work that outlives a single session: long refactors, multi-session features, security and compliance work where every conclusion needs an audit trail. The protocol picks the next step, so you stop re-explaining the project to every new session. **What this gives you:** - **Atomic progress:** every task is mechanically proven, not just claimed. - **Hierarchy over compression:** context is strictly structured, never lossily summarized. - **Absolute reproducibility:** every action is recorded, so any step, decision, or assumption can be replayed and retraced. - **Continuity across agents:** if an agent stops mid-goal, another agent on another client or model resumes from verified state. - **Total ownership:** every goal, decision, task, question, and assumption is stored in a persistent historical graph that belongs entirely to you. Grove enforces its rules as deterministic invariants stored in a single checksummed lockfile: the agent cannot declare work done without falsifiable evidence, start unready tasks, or hallucinate progress. Instead of lossy prompt compression or summarization, project state lives in a typed reasoning graph with machine-checkable edges, and each step receives exactly the execution packet it needs, and nothing more. Works with Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Cline, GitHub Copilot, and any other agent. **Grove includes a CLI, a built-in MCP server, and a drop-in agent skill bundle** so you can integrate it into your workspace immediately. > [!IMPORTANT] > A note on the desktop app shown below. It exists to make the graph, the evidence, and the health of a project visible at a glance, but it is still experimental and has not been tested on macOS yet. The CLI and the MCP server are the stable, tested interfaces. The UI is implemented without any JavaScript framework, mostly plain HTML, CSS, and Tauri, which keeps it fast, and the graph is rendered with WebGL. <p align="center"> <picture> <source type="image/webp" srcset=".github/assets/overview.webp" /> <img src=".github/assets/overview.png" alt="Overview" /> </picture> </p> <table> <colgroup> <col style="width: 33.3333%"> <col style="width: 33.3333%"> <col style="width: 33.3333%"> </colgroup> <tr> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/graph.webp" /> <img src=".github/assets/graph.png" alt="Interactive graph view" /> </picture> </td> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/graph_archived.webp" /> <img src=".github/assets/graph_archived.png" alt="Graph with archived nodes included" /> </picture> </td> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/packet.webp" /> <img src=".github/assets/packet.png" alt="Execution packet of a work item" /> </picture> </td> </tr> <tr></tr> <tr> <td width="33.33%"> The reasoning graph, explored live. </td> <td width="33.33%"> The same view at 143 nodes, history included. </td> <td width="33.33%"> All an agent needs for one work item, nothing more. </td> </tr> <tr></tr> <tr> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/work.webp" /> <img src=".github/assets/work.png" alt="Work items with DoR and status" /> </picture> </td> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/areas.webp" /> <img src=".github/assets/areas.png" alt="Areas with goals, work, and content health" /> </picture> </td> <td width="33.33%"> <picture> <source type="image/webp" srcset=".github/assets/themes.webp" /> <img src=".github/assets/themes.png" alt="Themes and the critical path" /> </picture> </td> </tr> <tr></tr> <tr> <td width="33.33%"> Work items tracked from proposal to done. </td> <td width="33.33%"> Goals, work, and content health per area. </td> <td width="33.33%"> Work grouped by theme, with the critical path. </td> </tr> </table> ## Agents lose context as projects grow Long-running agents suffer from context amnesia. Decisions, assumptions, and dependencies drift out of view as the session grows. A related failure is **unreliable self-reporting**: the agent declares work complete without sufficient evidence. This happens not out of deception, but because nothing in the environment prevents it. Standard task trackers inherently trust the executor. When a human checks a box in Jira, the work is assumed done. That is a reasonable default for humans. For autonomous agents it is a silent failure mode. Premature "done" declarations compound across long sessions into structural errors, until the codebase no longer matches what anyone believes it to be, and nobody can say why a given line exists. This is not theoretical. Grove evolved from a crude Markdown hypothesis into a protocol that today manages Merlin Guild, a closed-source production project of 200k+ lines of Rust and TypeScript, heavy on blockchain and cryptography. It scales because the protocol does not rely on the agent remembering or obeying the workflow correctly. ## Structure instead of compression The obvious response to context amnesia is more tooling: summarization, compaction, retrieval. All of these compress context, and compression loses information while hoping the loss does not matter. **Grove does not compress context. It structures it.** As a project evolves, its work is continuously organized into areas, goals, questions, assumptions, decisions, and executable work items. This hierarchy gives the agent a way to identify the context relevant to the current step instead of repeatedly carrying the entire project history into its context window. The result is not just better continuity; it also reduces token usage. The agent no longer loads unrelated project context simply to recover where it is and why the current task exists. ## Map the entire codebase in a single prompt What happens when you point a frontier model at a raw codebase with Grove attached? Without a protocol, an agent skims the files, hallucinates a quick summary, and loses the plot after a few steps. With Grove, it maps the territory. In a real-world test on a complex codebase, a single prompt initiated a 5-hour autonomous Discovery session. The agent burned through its context window limit, but the result was a fully populated reasoning graph: **44 Areas, 47 Goals, and 89 Work items** targeting test coverage gaps and logic bugs. It didn't just dump a flat to-do list; it formally declared its open unknowns as Questions and grouped related efforts into Themes. Here is the exact prompt used to bootstrap the project: > Load the Grove skill and connect to the MCP server. Study the skill fully to understand the protocol constraints. > > Your objective is to run a complete Discovery phase across the entire codebase. Do not write implementation code yet, your job is project analysis and graph construction. > > 1. Break the project down into Areas. Note that a single package may contain multiple logical areas. > 2. Iterate through each Area and create Goals to address missing test coverage and explicit logic bugs. > 3. For each Goal, create Work items strictly formatted according to the Grove protocol. > 4. Group related work into Themes. > 5. Declare open unknowns as Questions and formalize architectural choices as Decisions where necessary. Because Grove enforces a Definition of Ready (DoR), the agent couldn't fake progress. Over the next day, the agent systematically executed the delivery phase, turning **75 tasks to Done**. The remaining tasks correctly stalled in `proposed` or `ready` states, waiting for human answers to the blocking Questions the agent had raised. <p align="center"> <picture> <source type="image/webp" srcset=".github/assets/demo.webp" /> <img src=".github/assets/demo.png" alt="" /> </picture> </p> ## One project state, multiple interfaces > The unit of memory is not the conversation. It is the project. > The unit of progress is not the agent's claim. It is verified evidence. Grove replaces polite prompt instructions with a strict, mechanically enforced protocol. Agents interact with project state through the CLI, MCP, and desktop interfaces. The protocol itself enforces the rules: - A work item cannot be marked done without an evidence record. - Work cannot start until every precondition is machine-verified. - Goal progress cannot be updated by hand; fitness deltas are applied atomically at close time or not at all. The state either satisfies the protocol, or Grove refuses to advance it. An agent cannot advance protocol state by merely claiming that work is complete. ## Give agents only the context they need Grove forces the agent to decompose the product into a strict typed hierarchy. Instead of a raw list of tasks, every piece of planning context lives explicitly in a node taxonomy. Nothing hides in side documents or the agent's internal state: | Node | ID | What it holds | | --- | --- | --- | | **Area** | `A-NN` | Permanent scope skeleton above goals; never archived. | | **Goal** | `G-NN` | Outcome with a measurable fitness function. | | **Theme** | `T-NN` | Optional grouping of related work items. | | **Work** | `W-NN` | Executable unit with Definition of Ready + Definition of Done. | | **Decision** | `D-NN` | ADR: immutable once accepted, superseded only with recorded rationale. | | **Question** | `Q-NN` | Open unknown, declared instead of pretended away. | | **Assumption** | `B-NN` | Falsifiable hypothesis with a validation method and result. | | **Discovery** | `Y-NN` | Reusable, evidence-backed knowledge distilled from finished work. | Typed edges connect these nodes into a graph, with blocks remaining acyclic. This structure lets Grove answer both **why does this task exist?** and **what breaks if I change it?** without relying on the agent's internal state. Once this graph exists, the routing promised above becomes mechanical. `grove next` picks the current step; `grove packet` emits exactly its context. Nothing irrelevant enters the context window. Before touching a line of code, the agent queries the **causality cone**. `grove packet W-NN --cone` maps the backward cone (everything that must finish first, in topological contraction order), the forward cone (the blast radius if this item changes), and a fragility score per affected goal. <p align="center"> <picture> <source type="image/webp" srcset=".github/assets/diagram.webp" /> <img src=".github/assets/diagram.png" alt="The Grove loop: on the left, the Discovery track chains Questions into Assumptions into Discoveries; on the right, the Project holds areas, each chaining Goals into Work into Evidence. Dotted edges close the loop: questions are asked against goals, assumptions target work, discoveries guide goals, and evidence distills back into discoveries." /> </picture> </p> ## Turn reasoning into reusable knowledge Grove introduces a unified methodology for AI-driven software development, informed by Dual-Track Agile, Hypothesis-Driven Development, ADRs, Continuous Discovery, Cynefin, and the Mikado method. These influences are integrated into a single workflow designed around the constraints of autonomous LLM agents and enforced through machine-checkable invariants. Most AI workflows are tiny waterfalls: specify everything, then build everything. Grove runs discovery and delivery in parallel, each track feeding the other: - **Discovery** takes open unknowns and operationalizes them. A question becomes a falsifiable assumption; validated outcomes become curated discoveries. - **Delivery** executes ready work items and writes verified code on top of those assumptions. The joints are mechanical. Questions are asked against goals; assumptions target work and gate it; discoveries guide the next goals; finished work distills back into discoveries. When a test falsifies an assumption, the plan reshapes at once; dependent work cannot proceed on a broken foundation. ### Knowledge has a lifecycle Grove does not treat distilled knowledge as permanent truth. Discoveries can become stale as the project evolves; reactivating one requires a fresh anchor. Distillation debt is tracked rather than silently accumulating, while goal fitness is re-derived on every close. The dashboard reflects actual protocol state after every mutation, not intended state. Grove assumes that a project keeps moving: knowledge changes, assumptions are invalidated, and unfinished reasoning accumulates. The protocol makes those changes visible instead of letting them disappear into project history. ### Ideas behind the protocol - Discovery and Delivery run in parallel (Dual-Track Agile, Cagan). A work item cannot enter Delivery until every open question and unvalidated assumption that blocks it is resolved in Discovery. - Every executable unit has explicit acceptance criteria before code is written (HDD, Definition of Ready). The DoR is not a checklist anyone can override; it is a boolean conjunction the CLI evaluates on every `status=progress` transition. - Long-lived design choices are first-class artifacts (ADR, Nygard). Decisions are immutable once accepted. They cannot be quietly revised; they can only be superseded by a new decision with a recorded rationale. - Open unknowns are first-class artifacts; agents declare them rather than pretend to know (Continuous Discovery; Cynefin). A question tagged `chaotic` halts the agent and requires human resolution. - Assumptions are falsifiable gates, not comments. An assumption in state `invalidated_blocking` prevents any dependent work item from becoming ready. The agent cannot proceed by ignoring it. - Refactoring uses a Mikado-style dependency graph distinguishing causation, sequencing, implementation, and inquiry. This makes the blast radius of a change explicit before the first line is touched. - Verified goals archive only after distillation: their validated assumptions, answered questions, and accepted decisions become Discoveries (Y), curated domain axioms that are never archived and that feed future packets. - Areas (A) are a permanent scope skeleton above goals. Every goal belongs to exactly one area, enforced by the CLI at creation (I₁₃); areas are never archived, so the structure outlives any single goal. ## Beyond spec-driven development Spec-driven development makes specifications explicit. Grove goes one step further: it makes the development process itself executable and verifiable. A specification describes what the system should do. Grove additionally models the state of the work around it: what is proven, what is assumed, what is blocked, what is ready, what is done, and on what evidence. These are not instructions for the agent to follow; they are protocol state that gates what the agent is allowed to do next. This changes the workflow from document-driven execution to state-driven execution. There is no single specification to regenerate the project from and no fixed waterfall per feature. Discovery and delivery run continuously, and when an assumption is falsified, the graph and the execution plan change with it. Every state transition is mechanically gated rather than relying on the agent to follow the process correctly. Specifications remain useful. In Grove, they can live as decisions, acceptance criteria, and other structured project knowledge attached to the work. What changes is what enforces them: the specification describes the intended outcome; the protocol determines whether the project is allowed to advance. ## Let evidence decide when work is done A task cannot even start until a Definition of Ready passes. This is a strict boolean conjunction evaluated by the protocol on every `status=progress` transition, not a checklist anyone can override. Once ready, Grove emits an execution packet: exactly the context the step needs (the work item, its acceptance criteria, its open questions, its assumption chain, and the decisions that constrain it) and nothing more. Closing requires **falsifiable** evidence: test outputs, commit hashes, build logs. A self-reported `finished` is not accepted. The transition to `done` is **atomic**; goal fitness deltas and status re-derivation are applied in the same write, or not at all. ## Versioned reasoning, not just versioned code All state lives in `.grove/state.lock`, a single line-oriented text file with a SHA-256 checksum rewritten on every mutation. Any manual edit, rogue script, or bad merge is detected on the next protocol operation, and all state transitions are blocked until the file is repaired. The lockfile can live **inside** the project repository, so the history of project reasoning evolves alongside the code, or **outside** it in a separate directory or repository. Both topologies are supported. When committed to version control, the lockfile's history becomes the history of the project's reasoning, not just its code. ### Merge conflicts and race conditions A typical race occurs when two branches advance project state independently: 1. Branch `A` merges into `main` and advances the project state. 2. Branch `B` was created earlier and still contains the previous state checksum. 3. Merging the branches produces a checksum mismatch. Grove detects the divergence instead of silently accepting inconsistent state. Resolution is mechanical: 1. Resolve textual conflicts, keeping records from both sides. 2. Run `grove repair --confirm` to re-canonicalize and re-checksum the state. 3. Run `grove check` to surface any invariant violations. 4. Run `grove renumber` if ID collisions occurred between branches. ### Parallel work For parallel worktrees, `grove init --id-stride/--id-offset` allocates disjoint ID ranges so collisions do not happen in the first place. On a single machine, concurrent mutations are protected by an exclusive `flock`, while claimed work is protected by session tokens. Multi-machine writes to a single lockfile are out of scope by design. Remote state transitions must be routed through a single canonical writer, such as a primary CI agent. ## Executable history, not just an audit trail Git versions code. Grove versions the reasoning that produced it. Most agent harnesses and SDD (Spec-Driven Development) tools lose the "why" the moment a task is closed. Grove records every action into a persistent, executable journal, giving you something unprecedented: a full undo and replay at the level of project decisions. Every mutation appends one JSON line to `.grove/journal.log` holding the command, the UTC timestamp, the session token that wrote it, and the exact inverse of the change. ```json {"v":1,"ts":"2026-07-19T12:35:19Z","cmd":"set","inv":{"op":"set_status_plain","id":"B-01","old_status":"testing"},"session":"host:0123456789abcdef"} ``` Because every record carries its own inverse, the journal is executable. grove undo replays these inverses in reverse order, restoring the exact prior state down to goal statuses, fitness deltas, and session claims. Git rolls back the implementation; Grove rolls back the hypothesis, the assumption status, and the goal fitness that justified it. This unlocks true project replay. You can take the state at t=0 and replay the journal to see exactly how the project arrived at its current shape. It acts as a git blame for decisions: instead of just seeing who wrote a line of code, you retrace what assumption was validated, what evidence forced a pivot, and why a specific path was chosen. The journal also captures the agent's invisible work. When the Definition of Ready (DoR) guard rejects a transition, the journal records the exact conjuncts that failed. Audit records such as gate runs, rejections, and undos are never inverted and never truncated. This captures what the agent attempted, not only what it changed. This persistent trail powers grove log and grove stats: reconstructing cycle times, DoR first-pass rates, and content health at any point in history. Because it is written in plain JSON lines, it requires no special permissions to read, serving as the raw material for building your own metrics or conducting post-mortem analyses of agent failure patterns. ## Continue when the agent disappears A work item in progress carries an exclusive session token (only the session that claimed it can mutate it). If a provider goes down mid-goal, or a tough refactor calls for a different model, another agent on another client takes over via `grove handoff`. Alternatively, it adopts the session via `grove resume`. All reasoning and proof live in the lockfile, so `grove next` and `grove packet` rebuild the working context instantly. The invariants keep the new agent honest; the rest of the progress cannot be faked. The real test of agent-driven development is exactly this: when the agent stops mid-goal, the next one picks the project up without reconstructing intent from chat logs. ## Preserve why the work exists The result is not only continuity for agents. It is explainability for the people who own the project. You can answer why a piece of code exists, what it depends on, what assumptions it rests on, and what evidence justified it months after the original work was completed. ## Getting started Grove is designed to be installed once and then used as the persistent workflow layer for your project. The [installation guide](docs/install.md) covers the CLI, MCP server, desktop application, and agent skill bundle. Then run `grove init` in your project root to create the checksummed state file. Connect the MCP server, add the [signed skill](docs/install.md#agent-skill-bundle), and bootstrap your first session with a [prompt template](docs/prompts.md). From then on, `grove next` drives every session. Not sure if Grove fits your workflow? The [Gemini Notebook](https://notebook.google.com/notebook/434f3efc-c199-4b7e-ac61-92fbd85d655e) holds the full documentation. Start with a simple question, like *"How does Grove stop an agent from marking work done without evidence?"* or *"When is Grove the wrong tool for my project?"* ## Where it fits Grove is most useful when work is long-running, reasoning-heavy, and performed by autonomous agents. **Security and research workflows**: security work stretches over months and runs on hypotheses: most leads die, some become critical paths. Grove fits this shape natively. Every closed item carries evidence, so the audit trail is the project itself - the append-only journal, immutable decisions, and evidence-bound closes answer "who concluded what, when, and on which basis" without a separate reporting process. Priorities stop being a feeling: the critical path, per-goal fitness, and DoR gates decide what runs next, formally. **Architecture and compliance work**: assumptions in Grove carry a validation method and a result; decisions carry rationale; discoveries anchor invariants to concrete surfaces. "Do we still meet our SLOs" becomes a question the state answers through goal fitness metrics, and "why is it built this way" stays answerable months later - each architectural choice points to the questions, assumptions, and evidence that produced it. **Long refactors and multi-session features**: the Mikado-style dependency graph and the causality cone make blast radius explicit before the first edit, and session continuity lets the work survive agent and provider changes. Grove is usually the wrong tool for short-lived prototypes, one-prompt tasks, and projects where the code will not outlive the session. Grove is not a task manager, code-context tool, or multi-agent orchestrator. It is a protocol for maintaining verified project state for autonomous agents. ## Protocol invariants ```text I₁: ∀ w ∈ W with status = progress, DoR(w) ≡ ⊤. I₂: ∀ w with type = spike ∧ status = done, produces(w) ⊆ D ∪ Q ∪ B ∪ Y ∧ produces(w) ≠ ∅. I₃: ∀ w with status = done, ∃ ev ∈ Evidence, satisfies(ev, AC(w)). I₄: |{ w ∈ W : status(w) = progress }| ≤ WIP_LIMIT (default 2). I₅: ∀ (n₁, blocks, n₂) ∈ E, terminal⁺(n₁) before status(n₂) may transition to progress. I₆: ∀ t ∈ T, status(t) = done ⟺ ∀ w ∈ WI(t), status(w) ∈ { done, rejected, archived }. I₇: graph (N, E ∩ (· × {blocks} × ·)) is a DAG. I₈: ∀ q ∈ Q with cynefin(q) = chaotic, status transitions only via human. I₉: ∀ w ∈ W with type = feature, DoR(w) ⇒ ∀ b ∈ BChain(w), status(b) ∈ { validated, invalidated_acceptable }. I₁₀: status transition w → done is atomic with applying fitness deltas to each g ∈ goals(w) and re-deriving status(g). Either both succeed or neither does. The CLI rejects status=done unless deltas are staged in the same call (or pre-staged via `grove fitness` since the last status mutation of w). I₁₁: ∀ w ∈ W with status = progress, the session that set it is the only session permitted to mutate w until terminal(w) or w leaves `progress` (e.g. `revert` or another guarded status change). Persisted as header attrs `session` and `session_at` (UTC); `check` rejects a missing token (`grove resume` adopts; see protocol §2.6). I₁₂: ∀ y ∈ Y: (≥1 provenance edge: (w, produces, y) ∨ (y, distills, d/q/b)) ∧ (surface(y) ≠ ∅ ∨ why(y) ≠ ∅) ∧ tags(y) ≠ ∅ (≥1 glossary term). `proposed → active` is refused while any conjunct fails; `stale → active` only via `grove revalidate` paid with a fresh anchor. I₁₃: ∀ g ∈ G: ∃ a ∈ A with area(g) = a.id, recorded as the mandatory `area` field and enforced at creation (`grove add g --area=A-NN`); re-partition via `grove set G-NN area=A-NN`. An area-less goal in the lock is a violation, never silently repaired. ``` with terminality: ```text terminal(w ∈ W) ⟺ status(w) ∈ { done, rejected, archived } terminal⁺(g ∈ G) ⟺ status(g) = verified (strict for blocks edges) terminal(g ∈ G) ⟺ status(g) ∈ { verified, declined } terminal(d ∈ D) ⟺ status(d) ∈ { accepted, rejected, superseded } terminal(q ∈ Q) ⟺ status(q) ∈ { answered, deferred, dropped } terminal(b ∈ B) ⟺ status(b) ∈ { validated, invalidated_acceptable, invalidated_blocking } terminal(t ∈ T) ⟺ status(t) = done terminal(y ∈ Y) ⟺ status(y) = superseded terminal(a ∈ A) ⟺ ⊥ (areas have no lifecycle) ``` `terminal⁺` is the strict variant used for `blocks` edges: a `declined` goal does not unblock dependents. Other relations use the lax `terminal`. ```text assumptions(w) ≜ { b ∈ B | (b, targets, w) ∈ E } BChain(w) ≜ assumptions(w) ∪ { b ∈ B | ∃ q, (q, asks, w) ∈ E ∧ (b, tests, q) ∈ E } produces(w) ≜ { n ∈ D ∪ Q ∪ B ∪ Y | (w, produces, n) ∈ E } goals(w) ≜ as recorded in `goals` field of w WI(t) ≜ { w ∈ W | theme(w) = t } ``` ## FAQ **How does the state file work?** All state lives in `.grove/state.lock`, a single line-oriented text file with a SHA-256 checksum on every write. Any manual edit is detected immediately on the next protocol operation, and all state transitions are blocked until the file is repaired. The agent never reads or writes the file directly; it interacts only through Grove interfaces (CLI, MCP). This design makes the entire workflow auditable and diff-friendly. Every transition is a single atomic write. The lockfile can be committed to version control; its history is the history of the project's reasoning, not just its code. **How does an agent work with Grove efficiently? Does it need to read the whole skill and write essays into the lock?** No on both counts. The skill's `index.md` is the minimal safe contract - one screen, complete for operation; every other page is depth you open only when the task touches its topic. And when a command's shape is unclear, the CLI itself is the instructor: refusals like `add g: --area is required` or `DoR ≢ ⊤; see grove dor W-NN` say exactly what is missing. Even an agent that never opened the skill cannot corrupt state, because the invariants (DoR gates, evidence gates, the checksum) are enforced by the protocol, not by the document - partial reading degrades process quality, never integrity. Writing works by compression, not by transcription. The agent deliberates in its own context for as long as it needs, then stores only the conclusions: one acceptance criterion per line, one sentence per hypothesis, a compact context/options block on a decision node. Dozens of small CLI calls are normal and cheap - they batch into a single shell invocation per node (`add` + fields + `fitness`). What never belongs in the lock is the reasoning itself: if a fact does not change what a future agent does, it is not recorded. And `grove next` / `grove packet` exist precisely so the agent never re-reads the state file to plan. ## License GNU Affero General Public License v3.0 (AGPL-3.0). Copyright (c) 2026 Alex Shelepenok. Free to use, study, modify, and redistribute under the license terms, including network use: offering Grove as a network service requires offering its source. See [LICENSE](LICENSE) for the full text.