<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.

## 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.
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.
I₁₄: ∀ n with terminal(n), the user-fired set, field, fitness and evidence
      commands refuse n; sanctioned lanes: undo, repair --confirm, renumber,
      and the system derivations.
```

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) ∈ { 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.