# Concepts

Agents propose and people decide: how Trov keeps what agents read trustworthy, and what live, staged, unpromoted and draft mean.

## What Trov holds

Trov is one organization's working memory, shared by its people and the coding agents they connect:

- **Docs**, in a Technical and a Product space, grouped into sections, with every version kept.
- **Decisions**: architecture decision records, in their own section of Docs.
- **The feed**: what shipped, from people and agents alike, each entry linked to its pull request, commit or issue.
- **Tickets and sprints**: the team's request queue, the roadmap's sprints and a short written plan.
- **Handoffs** from one session to the next, the team's **Prompt Library**, and **artifacts**: versioned pages and files (HTML, Markdown, SVG, Mermaid, images, PDFs).
- **The Repo dashboard**: deploys, CI, drift and usage, from what Trov has captured. What was never captured reads as unknown, never as zero.

An agent connects as a person ([Connect an MCP client](https://trov.dev/docs/connect)): it reads what that person can read, and everything it writes is recorded as theirs. A name an agent puts in a request as the author is ignored.

## Agents propose, people decide

A wrong doc gets believed by every agent that reads it after. So the rule is about what an agent may make official on its own: **nothing**. Knowledge an agent proposes is **staged**, and a person confirms it. Work that is a request or a plan, not a claim, takes effect at once, bounded by who may do it:

| | Staged: a person confirms | Direct: takes effect now |
|---|---|---|
| What | doc changes, decisions (ADRs), feed entries | tickets, sprints, the roadmap plan, artifacts, handoffs |
| Agent tools | `propose_doc_update`, `append_feed`, `record_session` | `create_ticket`, `transition_ticket`, `create_sprint`, `upload_asset`, `send_handoff`, … |
| What bounds it | the gate, then a person's verdict | scope: your own lane, or a role |

**Confirming is a person's act in the signed-in web app**: promote or reject a doc change, ratify or reject a decision, place or discard what Triage holds, publish a prompt, ratify an artifact. No MCP tool does any of these, and those routes refuse any request that carries a token. Rejected proposals and old versions are kept, never deleted.

## The gate

Every proposal goes through one gate, whichever way it arrives (`record_session`, `propose_doc_update`, `append_feed`, or the `/ingest` API):

- **Sending the same thing twice changes nothing.** A replayed batch, or a body identical to what is there, is dropped as `unchanged`.
- **Each doc change is classified** `new`, `edit` or `rewrite` by the server, against the live version. The version the writer read (`base_version`) is kept, so an edit written against an out-of-date version is flagged.
- **Nothing is guessed.** A section or tag outside the team's vocabulary, or a new doc proposed with low confidence, goes to **Triage › Unplaced** for a person to place. Low confidence on an existing doc stages it, flagged for a closer look.
- **A doc embeds only images uploaded to Trov.** A proposal pointing at any other image source is refused, and nothing is staged.

What passes is **staged**: the live doc is untouched until a person promotes the change in **Triage › Review**, which shows it as a diff (unified, side by side, or rendered).

## Live, staged, unpromoted, draft

Every result an agent reads from `query` carries an `authority`. Treat anything that is not `live` as not settled:

- `live`: settled. A person promoted or ratified it. Trust it.
- `staged_pending`: a newer version is staged but not promoted. The body shown is still the live one; the proposal comes beside it.
- `unpromoted`: exists only as staged content and was never promoted. A draft, not the truth.
- `draft`: a decision that has not been ratified, or an artifact still in draft.

Artifacts have their own statuses: `draft`, `published` (shared, one person's word) and `ratified` (a person's sign-off on the latest version, the only team-confirmed one). A prompt an agent saves is `staged` until a person publishes it.

## Who may change what

- **Tickets.** Anyone, and any agent, may file one. Every other ticket write by an agent needs the ticket to be assigned to its person already; assigning (`assign_ticket`) is for an admin, the ticket's requester or a current assignee.
- **Sprints** are open to every member, people and agents alike. Rewriting the whole plan (`update_plan`) is for admins.
- **Nothing infers a resolution.** A merged pull request, a closed issue, the clock or every ticket being done never closes a ticket or finishes a sprint: a person does. The one exception is a ticket mirrored from a GitHub issue, which follows its own issue's close and reopen.
- **Admin is a role in an organization** (admin or owner). Inviting people and connecting repositories are an admin's; the plan and its billing are an owner's.

## The loop: orient, work, record

1. **Orient.** Before working an area the team already knows, the agent searches Trov (`query`) and reads what is settled. The Claude Code plugin's `load-context` skill does this by itself.
2. **Work**, building on what the team decided instead of guessing.
3. **Record**, only when a person asks. The agent reads what actually shipped from `git` and GitHub, reads back each doc it touches, and sends one batch (`record_session`). It is staged, and waits for a person.

Between sessions, a **handoff** carries where a task stands to the next session (yours, a teammate's, or anyone's); unclaimed ones expire after 7 days.

## One connection, several organizations

A person can belong to several organizations, and one agent connection can reach all of them. Each call acts in exactly ONE, chosen only among the person's own live memberships: a connection that follows the repository acts in the organization that has the call's `repo` connected; a manual one in its current organization; a pasted token in the one it was made for. When no organization fits, nothing is read or written, and the error says what to do. Nothing in a refusal reveals another organization.

Trov's source is public under AGPL-3.0: [github.com/AndresL230/trov](https://github.com/AndresL230/trov).

---

This page: https://trov.dev/docs/concepts · All docs for language models: https://trov.dev/llms.txt