Metadata-Version: 2.4
Name: causum-vesta
Version: 0.6.1
Summary: Answers structural questions about a repository from a resolved graph, an ontology of what the work is called, and what earlier sessions worked out — and leaves a witness per decision
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: sidecar
Requires-Dist: mcp>=1.9; extra == "sidecar"
Dynamic: license-file

# Vesta

Answers structural questions about a repository from a resolved graph of what
refers to what, an ontology of what the work is called, and what earlier
sessions already worked out — so an agent can ask instead of reading, and you
do not pay twice for the same understanding. Every decision it narrows leaves
a compact, checkable **witness** (`spec/witness.md`).

## The one design rule to understand first

**Vesta ships no model, holds no API key, and makes no network calls of its
own.** That is not a claim in this README — the test suite poisons the
model-client imports and asserts every tool still answers
(`tests/test_conformance.py`).

So where does judgement come from? From the harness you already run. Vesta
nests inside your coding agent and uses *its* inference — the model you
already pay for, under the credentials you already control. Anything Vesta
cannot compute deterministically is judged there, and recorded as such.

The rule, stated once: **Vesta may speak to a model you point it at; it never
ships a client for one.** Today that means there is no configuration anywhere
in Vesta that makes it call a vendor — nothing to leak, no bill of its own,
and installing it requires no decisions.

## Pick your setup

Three ways to run it. Start with the row that describes you.

| you have | install | what works |
|---|---|---|
| **Claude Code** | two lines, below | everything — hooks, tools, agents, automatic vocabulary |
| **another editor** (Cursor, Kiro, Codex, Copilot, Windsurf, Antigravity) | `pip install 'causum-vesta[sidecar]'` + MCP config | all fifteen tools; no hooks, no subagents (see below) |
| **a plain terminal, or CI** | `pipx install causum-vesta` | the full CLI: graphs, impact, defects, rules, guided narrowing, witnesses |

### Setup 1 — Claude Code (recommended: everything works)

    /plugin marketplace add https://gitlab.com/causum/vesta.git
    /plugin install vesta@causum

Nothing else to configure — hooks, slash commands, and the MCP server load
together. Confirm it's live:

    /vesta:shape

If that answers with real numbers, it's working. If it says nothing is built
yet, see **Housekeeping**. After any Vesta update, run `/mcp` once — the MCP
server is a background process and keeps old code in memory until reconnected.
If an answer looks stale right after an update, that is the first thing to
try.

### Setup 2 — another editor, over MCP

    pip install 'causum-vesta[sidecar]'

Then point your editor's MCP configuration at the `vesta-sidecar` command.
**`doc/other-editors.md` has the exact config block for each editor**,
including which instruction file each one reads unconditionally and what to
put in it so the tools get used unasked.

What you give up outside Claude Code, honestly: hooks (context injected
*before* the agent decides anything — the single most effective mechanism we
measured) and subagents (automatic vocabulary derivation, rule recovery).
Those are Claude Code conventions with no equivalent elsewhere. The
vocabulary and rules still work — you supply them by hand, exactly as in
Setup 3.

### Setup 3 — the CLI alone, no agent anywhere

    pipx install causum-vesta

Everything deterministic works immediately, on any repository:

    vesta status --prepare     # build the graph (needs a language server, below)
    vesta shape                # what this repository is made of
    vesta uses <name>          # a definition and everything that refers to it
    vesta touches <file>       # what a change reaches, and which tests cover it
    vesta defects              # things worth fixing, found unasked
    vesta projects             # every repository Vesta holds, by name and path

Two things normally derived by an agent need one manual step each, and both
degrade to honest answers rather than wrong ones until you do:

- **Vocabulary** — what the work here is *called*, so `vesta does "post a
  transaction"` can answer in the code's names. Seed it from a shipped
  template (`vesta words --template ai`), write your own terms
  (`vesta-domain --repo . --write`), or let an agent derive it if you ever
  open the repo in one.
- **Rules** — things you've decided that the code must honour:
  `vesta learn --declare "never a bare except in this repository"`, then
  `vesta decided --check`.

With those in place the accountable core runs harness-free: `vesta honing`
narrows a decision guided by your active specification, and every run leaves
a **witness** under `~/.vesta/witnesses/<project>/` — a few-kilobyte record
of what was asked, how the space contracted, what was overridden, and which
checks held. In CI, that file is the artifact: keep it with the build.

## Which model does what (and where)

Inside Vesta itself: **none, ever.** In Claude Code, judgement tasks run as
subagents on your session's inference — reading and labelling definitions on
a small model (`haiku`), because it happens once per definition; synthesis
somebody will be held to (a contract, a specification) on a larger one
(`sonnet`), once. Each subagent declares its model in its own frontmatter;
nothing defers to whatever your session happens to have selected. Outside a
harness there is no model, and everything above still works as described.

## Language support

Vesta resolves through a real language server per language — the machinery
behind your editor's "go to definition," not a name-matching guess:

| Language | Server | Install |
|---|---|---|
| Python | `pyright-langserver` | `npm i -g pyright` |
| Rust | `rust-analyzer` | usually ships with `rustup` |
| Go | `gopls` | `go install golang.org/x/tools/gopls@latest` |
| C / C++ | `clangd` | ships with LLVM, or your package manager |
| JavaScript / TypeScript | `typescript-language-server` | `npm i -g typescript-language-server typescript` |
| OCaml | `ocamllsp` | `opam install ocaml-lsp-server` |
| Lua | `lua-language-server` | your package manager |

A language with no server installed is reported as unresolved (in
`vesta status`'s hole count), never silently skipped. Adding a language is
one row in `vesta/resolve.py` — a name, a command, and the suffixes it owns.

## Day to day, inside a session

Every tool is a slash command in Claude Code and an MCP tool everywhere else:

    /vesta:shape      what this repository is made of, before opening a file
    /vesta:touches    what a change reaches, and which tests cover it
    /vesta:does       where a kind of work happens, asked in ordinary words
    /vesta:defects    things worth fixing, found without being asked
    /vesta:decided    rules you have stated, and whether the code honours them
    /vesta:honing     whether you're honing in, or just going round again
    /vesta:why        why it concluded that, and whether it still holds today
    /vesta:tutorial   learn it a page at a time, on your own repository

`/vesta:help` lists the rest. Most of the time none of this needs typing —
Vesta watches what you're about to do and puts what it knows in front of the
agent unasked: defects in the file you're about to change (named once, not
repeated), a rule this work would break, what earlier sessions worked out
about a definition the prompt names. It says nothing on a prompt that names
nothing, which is most of them.

**`does` is the one that is not a grep.** Ask in the vocabulary of the work —
"retrying a failed request", "posting a transaction" — and it answers in the
vocabulary of the code. Word forms cross (plurals, verb forms); genuine
synonyms do not, deliberately — a match you can't explain is a match that can
be quietly wrong. When nothing crosses, the answer carries the repository's
own vocabulary so you (or the agent) can re-ask in its words.

## Adjudication and ontology

Two things Vesta asks you to confirm, because guessing on your behalf and
asserting it as fact would be worse than asking:

**Rules.** Vesta recovers candidate standing rules from corrections you gave
an agent in earlier sessions — only you know which were decisions.
`/vesta:learn` shows what's waiting; `vesta learn <handle> rule` confirms one
from a terminal; `vesta learn --declare "…"` states one outright. A recovered
rule must quote words you verifiably said.

**Vocabulary.** Derived per repository, automatically, the first time it
matters in Claude Code — or supplied by you (`vesta words --edit`, templates,
`vesta-domain --write`). A template lends words for a category of system,
never a claim about which of *your* definitions do that work; that binding is
always read from your code.

## Housekeeping

    vesta status               is it built, and what's in it
    vesta held                 everything Vesta holds, across every repo, biggest first
    vesta held --reclaim       delete what belongs to repos that no longer exist

Everything derived lives under `~/.vesta` and nowhere else, keyed per
project — one project's graph, vocabulary, rules, and witnesses never mix
with another's. Deleting `~/.vesta` is a full, clean reset.

## What it will not do

- **Read anything hidden.** Nothing beginning with a dot is ever walked — not
  `.env`, not `.aws`, not `.ssh`. Nor dependency directories: `venv`,
  `node_modules`, `site-packages`, `vendor`, and the rest.
- **Assert what it has not derived.** A rule is recorded against words you
  actually said; a template lends vocabulary but never bindings.
- **Imply a complete answer.** What could not be resolved is reported — a
  propagation set says which references it could not follow.
- **Call a model on its own.** See the design rule at the top; it is load-
  bearing, and it is tested.

## What has and has not been measured

On a read-only structural question against this repository, paired with a
control run of the same prompt and costed by the host's own `/cost`:

| arm | mechanism | cost | vs control |
|---|---|---|---|
| control | no Vesta | $0.4872 | — |
| tools | the agent calls them | $0.3747 | −23.1% |
| injection | put in front, unasked | **$0.2980** | **−38.8%** |

Injection delivered 799 characters before the agent decided anything; the
tools delivered 21,905 across three calls. A separate benchmark (`bench/`)
checks `uses()` against ground truth derived independently of Vesta's own
graph: mean precision 0.998, mean recall 1.000. `doc/measurements.md` has the
rest, `doc/open-questions.md` records what is still unmeasured, and
`spec/witness.md` specifies the witness format, its checks, and its stated
limits.

## Requirements

Python 3.10 or newer, and a language server for the languages you want
resolved. The Claude Code plugin builds its own runtime on first use and does
not touch yours; the PyPI install uses the Python you install it into. One
runtime dependency: `pydantic`.

## Licence

Apache 2.0. See `LICENSE` and `NOTICE.md`.
